SANEI  1.0.27-229-gef85977e-dirty
Macros | Functions
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 arithmatic 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
argsargument 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 occured 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 occured 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