Merge branch 'feature/upstream' into develop

1 files changed, 35 insertions, 3 deletions

diff --git a/include/sane/sanei_thread.h b/include/sane/sanei_thread.h
index fa72481..6e68964 100644
--- a/include/sane/sanei_thread.h
+++ b/include/sane/sanei_thread.h
@@ -94,6 +94,38 @@ extern SANE_Bool sanei_thread_is_forked (void);
  */
 extern SANE_Bool sanei_thread_is_valid (SANE_Pid pid);
 
+/** 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
+ */
+#define sanei_thread_invalidate(pid) ((pid) = (SANE_Pid)(-1))
+
+/** 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.
+ */
+#define sanei_thread_initialize sanei_thread_invalidate
+
 /** Spawn a new task.
  *
  * This function should be used to start a new task.
@@ -131,7 +163,7 @@ extern int sanei_thread_kill (SANE_Pid pid);
  * @param pid - the id of the task
  * @param sig - the signal to send
  *
- * @return 
+ * @return
  * - 0 - on success
  * - any other value - if an error occured while sending the signal
  */
@@ -139,7 +171,7 @@ extern int sanei_thread_sendsig (SANE_Pid pid, int sig);
 
 /** Wait for task termination.
  *
- * This function waits until a task that has been terminated by 
+ * This function waits until a task that has been terminated by
  * sanei_thread_kill(), sanei_thread_sendsys() or by any other means
  * is finished.
  *
@@ -153,7 +185,7 @@ extern SANE_Pid sanei_thread_waitpid (SANE_Pid pid, int *status);
 
 /** Check the current status of the spawned task
  *
- * 
+ *
  * @param pid - the id of the task
  *
  * @return