Changeset 18953 for trunk/psLib/src/sys/psThread.h

Timestamp:

Aug 8, 2008, 8:05:09 AM (18 years ago)

Author:

Paul Price

Message:

Cleaning up thread functions, documenting header. Added 'harvest' option to psThreadPoolWait to save user from the trouble of harvesting. Fixed memory problem with psListGetAndRemove.

File:

• trunk/psLib/src/sys/psThread.h (modified) (2 diffs)

trunk/psLib/src/sys/psThread.h

@@ -4 +4 @@
  *
  *  @author EAM, IFA
- *  @version $Revision: 1.2 $ $Name: not supported by cvs2svn $
- *  @date $Date: 2008-07-31 23:56:29 $
+ *  @version $Revision: 1.3 $ $Name: not supported by cvs2svn $
+ *  @date $Date: 2008-08-08 18:05:09 $
  *
  *  Copyright 2004-2005 Insitute for Astronomy, University of Hawaii
@@ -16 +16 @@
 /// @{
 
+/// Job to be executed on a thread
+///
+/// This job is passed to the function that executes it
 typedef struct {
-    psString type;
-    psArray *args;
+    psString type;                      // Type of thread
+    psArray *args;                      // Arguments to job
 } psThreadJob;
 
+#define PS_ASSERT_THREAD_JOB_NON_NULL(JOB, RVAL) \
+if (!(JOB) || !(JOB)->type || !(JOB)->args) { \
+    psError(PS_ERR_UNEXPECTED_NULL, true, "Thread job %s or one of its components is NULL.", #JOB); \
+    return RVAL; \
+}
+
+/// A thread, which executes a job
+///
+/// Wraps pthread with a few extra conveniences
 typedef struct {
-    bool busy;
-    bool fault;
-    pthread_t pt;
+    bool busy;                          // Is the thread busy?
+    bool fault;                         // Has the thread faulted?
+    pthread_t pt;                       // The thread itself
 } psThread;
 
-typedef bool (*psThreadTaskFunction)(psThreadJob *job);
+/// Function to execute a thread job
+typedef bool (*psThreadTaskFunction)(const psThreadJob *job);
 
+/// Task that is executed on a thread
 typedef struct {
-    psString type;
-    int nArgs;
-    psThreadTaskFunction function;
+    psString type;                      // Type of task
+    int nArgs;                          // Number of arguments that function takes
+    psThreadTaskFunction function;      // Function to execute
 } psThreadTask;
 
-// typedef void *(*psThreadLaunchJobsFunction)(void *data);
+#define PS_ASSERT_THREAD_TASK_NON_NULL(TASK, RVAL) \
+if (!(TASK) || !(TASK)->type || (TASK)->nArgs < 0 || !(TASK)->function) { \
+    psError(PS_ERR_UNEXPECTED_NULL, true, "Thread task %s or one of its components is NULL.", #TASK); \
+    return RVAL; \
+}
 
-void psThreadLock ();
-void psThreadUnlock ();
 
-psThread *psThreadAlloc ();
+/// Lock the thread mutex
+void psThreadLock(void);
 
-psThreadJob *psThreadJobAlloc (char *type);
-bool psThreadJobAddPending (psThreadJob *job);
-psThreadJob *psThreadJobGetPending ();
-psThreadJob *psThreadJobGetDone ();
+/// Unlock the thread mutex
+void psThreadUnlock(void);
 
-psThreadTask *psThreadTaskAlloc (char *type, int nArgs);
-bool psThreadTaskAdd (psThreadTask *task);
-void *psThreadLauncher (void *data);
+/// Allocate a thread
+psThread *psThreadAlloc(void);
 
-bool psThreadPoolInit (int nThreads);
-bool psThreadPoolWait ();
-bool psThreadPoolFinalize ();
+/// Allocate a thread job
+psThreadJob *psThreadJobAlloc(const char *type);
+
+/// Add a pending job to the queue
+bool psThreadJobAddPending(psThreadJob *job);
+
+/// Get a job off the queue of pending jobs
+psThreadJob *psThreadJobGetPending(void);
+
+/// Get a job off the queue of done jobs
+psThreadJob *psThreadJobGetDone(void);
+
+/// Allocate a thread task
+psThreadTask *psThreadTaskAlloc(const char *type, // Type of task
+                                int nArgs // Number of arguments
+    );
+
+/// Add a task to the list
+bool psThreadTaskAdd(psThreadTask *task // Task to add
+    );
+
+/// Launch jobs on a thread
+void *psThreadLauncher(void *thread     // Thread (of type psThread)
+    );
+
+/// Initialise a pool of threads
+bool psThreadPoolInit(int nThreads      // Number of threads
+    );
+
+/// Return size of thread pool
+int psThreadPoolSize(void);
+
+/// Wait for the thread pool to finish
+///
+/// This function blocks (waits in usleep) until either an error is detected on one of the threads or until ll
+/// threads are idle and no jobs are left on the queue
+bool psThreadPoolWait(bool harvest      // Harvest the jobs from the queue?
+    );
+
+/// Clean up the thread pool
+bool psThreadPoolFinalize(void);
 
 /// @}