server_thread_pool_new()

server_thread_pool_t * server_thread_pool_new(const char *label, int stack_size, int min_threads, int max_threads, server_work_status_t(*func)(server_thread_t *, void *, server_thread_delayed_work_t **), int options, const char **wchans, int n_wchans)

Returns a new thread pool on success, or NULL on failure.

label

String used when ServerKit prints statistics

stack_size

Size in bytes of the per-thread stack to use

min_threads

Minimum number of threads in the pool

max_threads

Maximum number of threads in the pool

func

Function pointer to the worker function to use

options

Option flags for the thread pool, currently there is only one thread pool option:

SERVER_THREAD_POOL_QUEUE_ENTRY_SUPPLIED

Use of this option is preferred as it makes the queueing of work more efficient. This option results in the passing of SERVER_QUEUE_ENTRY_SUPPLIED to the internal ServerKit queue used by the thread pool.

As a result when you submit work to the thread pool you must do so in the form of a server_queue_entry_t *, and simply place your opaque data type which describes the work to your application in the foo member of the server_queue_entry_t structure.

wchans

An array of strings to be used as wait channel identifiers for notable procedures which may be delayed in the routines executed under the thread function. May be NULL if wchans are not to be used.

n_wchans

The number of wchan strings in the wchans array.

The function you provide must return a server_work_status_t, when your function is called it will be in response to work being available on the work queue for the thread pool.

Your function will get the server_thread_t object for the thread it is executing on in the first argument, the second argument is a void * which is the work unit you are working on, taken from the work queue. The type of this object would be known to you because you added work to the thread pool by casting something known to you to a void *, this pointer is being given back to you at the worker end now. When you use the SERVER_THREAD_POOL_QUEUE_ENTRY_SUPPLIED option the second argument should be instead treated as a server_queue_entry_t *, the same as you would have added to the thread pool. You would then find your work-specific type in the foo member of the server_queue_entry_t.

The third argument for the worker function is a pointer to pointer to a ServerKit type which is used for describing delayed work, server_thread_delayed_work_t.

When your worker function has work delayed, it populates a server_thread_delayed_work_t structure and stores the pointer to this structure in the address provided in the third argument by dereferncing it. After storing the description of the delayed work where the ServerKit worker function wrapper can find it, the worker must return a value from the server_work_status_t enum indicating delayed work.

Here are the members of the server_thread_delayed_work_t structure you need to set to let ServerKit manage your delayed work for you:

typedef struct _server_thread_delayed_work_t {
         /* file descriptor responsible for the delay */
        int     fd;

         /* how long delay can last in seconds */
        int     idle_time_remaining;

         /* how many times this work has been delayed */
        int     count;

         /* the work that is being delayed */
        void    *work;

        ...snip
} server_thread_delayed_work_t;

There are other members in the structure but you don't have to worry about them right now, working with this structure will probably be abstracted in the near future either with macros or a function.

Note that the space this structure is in must persist after the worker has returned the delayed status, so it must be malloc'd or something, it can't be on the stack.

This structure must be populated and assigned to the dereferenced pointer when you return either:

SERVER_WORK_DELAYED_WAIT_IN or SERVER_WORK_DELAYED_WAIT_OUT, which may be OR'd together to indicate both IN and OUT.

These other possible return values do not involve the delayed work structure:

When you wish to return unfinished work, you return: SERVER_WORK_UNFINISHED

When the work is completed, you return: SERVER_WORK_FINISHED

Upon completion, it is your responsibility to free the resources allocated for the work unit. Once you return SERVER_WORK_FINISHED, ServerKit will not do anything with the related work unit again.