sanei_thread.h File Reference

Support for forking processes and threading. More...

Go to the source code of this file.

Macros
#define	sanei_thread_invalidate(pid)   ((pid) = (SANE_Pid)(-1))
	Invalidate a SANE_Pid. More...
#define	sanei_thread_initialize   sanei_thread_invalidate
	Initialize a SANE_Pid. More...

Functions
void	sanei_thread_init (void)
	Initialize sanei_thread. More...
SANE_Bool	sanei_thread_is_forked (void)
	Do we use processes or threads? More...
SANE_Bool	sanei_thread_is_valid (SANE_Pid pid)
	Is SANE_Pid valid pid? More...
SANE_Pid	sanei_thread_begin (int(*func)(void *args), void *args)
	Spawn a new task. More...
int	sanei_thread_kill (SANE_Pid pid)
	Terminate spawned task. More...
int	sanei_thread_sendsig (SANE_Pid pid, int sig)
	Send a signal to a task. More...
SANE_Pid	sanei_thread_waitpid (SANE_Pid pid, int *status)
	Wait for task termination. More...
SANE_Status	sanei_thread_get_status (SANE_Pid pid)
	Check the current status of the spawned task. More...

Detailed Description

Support for forking processes and threading.

Backends should not use fork() directly because fork() does not work correctly on some platforms. Use the functions provided by sanei_thread instead. The build system decides if fork() or threads are used.

Please keep in mind that the behaviour of the child process depends on if it's a process or thread especially concerning variables.

In this file we use "task" as an umbrella term for process and thread.

See also

sanei.h sanei_backend.h

Macro Definition Documentation

sanei_thread_invalidate

#define sanei_thread_invalidate

(

pid

)

((pid) = (SANE_Pid)(-1))

Invalidate a SANE_Pid.

This "function" should be used to invalidate a SANE_Pid in a portable manner.

Note

When using pthreads, this only works for those implementations that opted to make pthread_t an arithmetic type. This is not required by the POSIX threads specification. The choice to do SANE_Pid invalidation by means of a macro rather than a proper function circumvents to need to pass a pointer. If we decide to implement SANE_Pid with a void* in the future, this can be changed into a proper function without the need to change existing code.

For details on the pthread_t type, see in particular Issue 6 of http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_types.h.html

sanei_thread_initialize

#define sanei_thread_initialize   sanei_thread_invalidate

Initialize a SANE_Pid.

This "function" should be used to initialize a SANE_Pid in a portable manner.

Note

This is at present just an alias of sanei_thread_invalidate. It seemed misleading to use the latter when intent clearly has initialization written all over it, hence the alias.

Function Documentation

sanei_thread_init()

void sanei_thread_init

(

void

)

Initialize sanei_thread.

This function must be called before any other sanei_thread function.

sanei_thread_is_forked()

SANE_Bool sanei_thread_is_forked

(

void

)

Do we use processes or threads?

This function can be used to check if processes or threads are used.

Returns

• SANE_TRUE - if processes are used (fork)
• SANE_FALSE - i threads are used

sanei_thread_is_valid()

SANE_Bool sanei_thread_is_valid

(

SANE_Pid

pid

)

Is SANE_Pid valid pid?

This function can be used to check if thread/fork creation worked regardless of SANE_Pid's data type.

Returns

• SANE_TRUE - if pid is a valid process
• SANE_FALSE - if pid is not a valid process

sanei_thread_begin()

SANE_Pid sanei_thread_begin	(	int(*)(void *args)	func,
		void *	args
	)

Spawn a new task.

This function should be used to start a new task.

Parameters

func()	function to call as child task
args	argument of the function (only one!)

Returns

• task id
• -1 if creating the new task failed

sanei_thread_kill()

int sanei_thread_kill

(

SANE_Pid

pid

)

Terminate spawned task.

This function terminates the task that was created with sanei_thread_begin.

For processes, SIGTERM is sent. If threads are used, pthread_cancel() terminates the task.

Parameters

pid	- the id of the task

Returns

• 0 on success
• any other value if an error occurred while terminating the task

sanei_thread_sendsig()

int sanei_thread_sendsig	(	SANE_Pid	pid,
		int	sig
	)

Send a signal to a task.

This function can be used to send a signal to a task.

For terminating the task, sanei_thread_kill() should be used.

Parameters

pid	- the id of the task
sig	- the signal to send

Returns

• 0 - on success
• any other value - if an error occurred while sending the signal

sanei_thread_waitpid()

SANE_Pid sanei_thread_waitpid	(	SANE_Pid	pid,
		int *	status
	)

Wait for task termination.

This function waits until a task that has been terminated by sanei_thread_kill(), sanei_thread_sendsys() or by any other means is finished.

Parameters

pid	- the id of the task
status	- status of the task that has just finished

Returns

• the pid of the task we have been waiting for

sanei_thread_get_status()

SANE_Status sanei_thread_get_status

(

SANE_Pid

pid

)

Check the current status of the spawned task.

Parameters

pid	- the id of the task

Returns

• SANE_STATUS_GOOD - if the task finished without errors
• any other value - if the task finished unexpectantly or hasn't finished yet