Please comment on API ...

[James Ladd]

As part of my Thread Pool library I have started to document the API before cutting code.
Please comment on what I have so far.

Code Select Expand


moved - see below.

All comments welcomed.

Rgs, James.

[Tedd]

Looks fine. Possibly a little wordy for each function :P
What I mean is that you could have "return: zero if no errors opening pool, else error code" instead of "return a zero value........"
(IMHO) brevity would be preferred (can also make it easier to understand sometimes.)

Also, section the paragraphs?
- function name
- purpose
- parameters
- return
- comments
(just seems a more logical ordering to me :wink)

*/
  jlc_tpool_open

  Open a thread pool to accept submitted tasks.

  ppPool - pointer to the location to store the address of the thread
           pool, if the function succeeds.

  tCount - count of threads in the pool, as an unsigned 32-bit integer.

  return: zero if no errors opening the pool, otherwise non-zero value
    indicating the error.

  A thread pool opened without error should be closed with
  jlc_tpool_close when no longer in use. A thread pool opened with
  an error should not be used and the pool should not be closed.
*/

I would capitalize the first character after any prefixes to make the difference obvious - pppool is 3 levels of pointer to an ool, or 2 to a pool? (ppPool makes it obvious.)

P.S. stop pee-ing in the pool :bg

[James Ladd]

Tedd,

Thats great feedback, I think Ill change my formatting to reflect what you had said.
Not too sure about the hngarian notation as im not a big fan, but maybe this once.
Update: I have modified the formatting to the ordering you have suggested.

Without seeing all the API's how do you feel about the functionality being provided
in the API ?

Do you think you would need to do more in opening a thread pool ?

Im also keen to keep the API small as possible to achieve a result and no more.

Rgs, James.

Code Select Expand


Moved - see below

Update: Added ui32 jlc_tpool_close

[Tedd]

Much better :U

I wasn't recommending the use of hungarian notation, just commenting on what you already had used. Personally I'm not such a fan, I do use 'p' to prefix pointers at it's helpful, but that's all :bg when your function start looking like "qbfznjpsfDoSomethingCrazy" then you know you're in trouble.

I can't comment on the functionality as I currently don't have use for a thread-pool :P But keeping in mind that you would like to keep it minimal, I would say you should add functionality as you find you need it (for your server stuff, right?) It's very easy to think of and add lots of amazing new functions... that no-one will actually need to use :bdg

[James Ladd]

Ted, Thanks.

Anyone else have comments?

Latest API doco

Code Select Expand


/*
  Conventions:

  . All jameladdcode function names start with 'jlc_' and take the form
    jlc_<noun>_<verb>(). However, in some cases the <noun> is not specified.


  . All jlc functions return zero (0) if there are no errors during
    the execution of the function and the results are usable. Otherwise the
    value returned identifies the error condition(s).

  . An attempt has been made to keep parameters consistent and uniform.

  . The API comments are organised into the following paragraphs:
    . function name
    . purpose
    . parameters
    . return
    . comments
   
  . The API is designed to provide the basic and minimum implementation
    necessary to be of use. Additional functionality may be added later.
   
  . Portions of this code are based upon the following work:
   
    http://www.cs.rochester.edu/u/michael/PODC96.html
   
    Maged M. Michael and Michael L. Scott.
    Non-Blocking Algorithms and Preemption-Safe Locking on Multiprogrammed
    Shared Memory Multiprocessors.
    Manuscript submitted for journal publication, March 1997.
*/

/*
  jlc_tpool_callback

  Defines the signature and arguments to the thread pool task callback function.
  This function is called by a worker thread in the pool when a task is to be
  serviced/run.
 
  tpool  - Pointer to the memory location where the address of the opened
           thread pool is stored.

  thread - Handle to the worker thread that is servicing the task.

  val1   - Value that was passed when the task was submitted.
 
  val2   - Value that was passed when the task was submitted.
           
  Return:  Zero if there are no errors running the task, otherwise a non-zero
           value indicating the error that occurred.

  It is recommended that this function be as quick as possible with long tasks
  broken into smaller ones that are submitted after the subsequent task
  completes.
 
  The signature of the callback is:
 
  ui32 jlc_tpool_callback(void** tpool, ui32 val1, ui32 val2, void* thread);
*/

/*
  jlc_tpool_open

  Open a thread pool of <tcount> threads to process tasks from
  a task queue of maximum <qcount> tasks.

  tpool  - Pointer to the memory location where the address of the opened
           thread pool should be stored.

  tcount - The maximum count of threads in the thread pool.

  qcount - The maximum count of tasks that can be queued waiting to be
           serviced by a thread in the thread pool.

  Return:  Zero if there are no errors opening the thread pool,
           otherwise a non-zero value indicating the error that occurred.

  A thread pool opened without error should be closed with the
  function jlc_thread_close when no longer in use. A thread pool opened
  with an error should not be used and should not be closed.

  Tasks can be submitted to the thread pool even if the task queue is full.
  In this situation the process submitting the task must wait for the task
  queue to be serviced by a thread for a free task queue slot to become
  available.

  It is recommended but not mandatory that more than one thread pool be
  created to handle tasks in a multi-threaded application, with a new thread
  pool created to handle tasks in different contexts. For example, one
  thread pool to service IO events and another to handle GUI events.

  It is recommended that tasks serviced by the thread pool run for as short
  a time as possible with larger tasks broken down into smaller tasks
  that can be submitted when a preceeding task is complete.

  The implementation of the thread pool may create all the threads and
  allocate all the memory necessary for the task queue at the time the
  thread pool is opened.
*/
ui32 jlc_tpool_open(void** tpool, ui32 tcount, ui32 qcount);


/*
  jlc_tpool_close

  Close and cleanup a thread pool.

  tpool  - Pointer to the memory location where the address of the opened
           thread pool is stored.

  drain  - Non-zero indicates draining required.
 
  millis - Time in milliseconds to wait for the pool to be drained.

  Return:  Zero if there are no errors closing the thread pool,
           otherwise a non-zero value indicating the error that occurred.
 
  The thread pool is closed and all resources are released. A thread pool
  pointer is invalid after this API returns.
 
  A <drain>ed pool will wait for each task in the pool to be serviced before
  closing and this may take some time to complete depending on the type and
  count of the tasks queued.
 
  A <millis> that is non-zero indicated the time in milli-seconds that the
  pool will wait for all tasks to be drained before the API returns. If
  <drain> is zero then <millis> as no effect and the pool will not be
  drained before it is closed. ie: the pool is forceably closed.
 
  A closed thread pool won't accept new task submissions.
 
  The initial implementation of the thread pool may not support the <millis>
  functionality and you should read the release notes to see when this
  is implemented.
*/
ui32 jlc_tpool_close(void** tpool, ui32 drain, ui32 millis);


/*
  jlc_tpool_submit

  Submit a task to the pool for servicing by a worker thread.

  tpool    - Pointer to the memory location where the address of the opened
             thread pool is stored.

  val1     - A value that is passed onto the task callback.
 
  val2     - A value that is passed onto the task callback.
 
  callback - Pointer to the task function.

  Return:  Zero if there are no errors submitting the task,
           otherwise a non-zero value indicating the error that occurred.

  A task is submitted to the thread pool by placing it on the queue of tasks
  to be serviced by worker threads. When a worker thread is free it will
  service the task by calling the <callback> and passing it <val1> and <val2>
  as well as other values. See the jlc_tpool_task API for details on the
  signature of the callback function and what arguments are passed to it.
 
  When this API returns with a zero value the task is queued.
 
  This API will not return until the task is queued. Special attention has
  been payed to the design of the queue to ensure it is thread safe and
  non-blocking. This should ensure that the time spent queueing tasks is as
  small as possible.
 
  A closed thread pool won't accept task submissions.
*/
ui32 jlc_tpool_submit(void** tpool, ui32 val1, ui32 val2, void* callback);


Can someone comment, I need closure ;)