X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcthread.h;h=5afc0a03201cced36b4b3cd48fd75fcb81c830b8;hb=e7b6c157b80152bf9fb9266e6bdd93f9fb0db776;hp=b13e31ba655a7a67d0a530a22e23a52f8395accf;hpb=c27a4ecc3e616e8a5ee09b8ca888ed6ff3e501f7;p=silc.git diff --git a/lib/silcutil/silcthread.h b/lib/silcutil/silcthread.h index b13e31ba..5afc0a03 100644 --- a/lib/silcutil/silcthread.h +++ b/lib/silcutil/silcthread.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 2001 - 2005 Pekka Riikonen + Copyright (C) 2001 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -21,16 +21,25 @@ * * DESCRIPTION * - * Interface for SILC Thread implementation. This is platform independent - * interface of threads for applications that need concurrent execution - * with the application's main thread. The threads created with this - * interface executes concurrently with the calling thread. + * Interface for platform independent thread implementation and thread pool + * system. The interface provides routines for applications that need + * concurrent execution with the application's main thread. The threads + * created with this interface executes concurrently with the calling thread. + * + * The thread pool system can be used to start many threads and execute code + * in the threads. The thread pool manages the threads creation and + * destruction. + * + * The interface also provides routines for accessing the Thread-local + * storage (Tls) on all supported platforms. * ***/ #ifndef SILCTHREAD_H #define SILCTHREAD_H +#include "silcschedule.h" + /* Prototypes */ /****s* silcutil/SilcThreadAPI/SilcThread @@ -92,6 +101,10 @@ typedef void *(*SilcThreadStart)(void *context); * If the `waitable' is TRUE then another thread must always issue * silc_thread_wait to avoid memory leaks. * + * On Symbian Cleanup Stack is created and new Active Scheduler is + * installed automatically for the created thread. The thread also + * shares heap with the calling thread. + * ***/ SilcThread silc_thread_create(SilcThreadStart start_func, void *context, SilcBool waitable); @@ -144,4 +157,233 @@ SilcThread silc_thread_self(void); ***/ SilcBool silc_thread_wait(SilcThread thread, void **exit_value); +/****f* silcutil/SilcThreadAPI/silc_thread_yield + * + * SYNOPSIS + * + * void silc_thread_yield(void); + * + * DESCRIPTION + * + * Yield the processor. The calling thread will yield the processor and + * give execution time for other threads, until its turn comes up again. + * + ***/ +void silc_thread_yield(void); + +/****s* silcutil/SilcThreadAPI/SilcThreadPool + * + * NAME + * + * typedef struct SilcThreadPoolStruct *SilcThreadPool; + * + * DESCRIPTION + * + * This context is the actual SILC Thread Pool and is returned by + * the silc_thread_pool_alloc function, and given as arguments to + * some of the silc_thread_pool_* functions. This context and its + * resources are freed by calling silc_thread_pool_free; + * + ***/ +typedef struct SilcThreadPoolStruct *SilcThreadPool; + +/****f* silcutil/SilcThreadAPI/SilcThreadPoolFunc + * + * SYNOPSIS + * + * typedef void (*SilcThreadPoolFunc)(SilcSchedule schedule, + * void *context); + * + * DESCRIPTION + * + * A callback function of this type is given as argument to the + * silc_thread_pool_run. The `schedule' is the scheduler and the + * `context' is the `run_context' given as argument to + * silc_thread_pool_run. + * + ***/ +typedef void (*SilcThreadPoolFunc)(SilcSchedule schedule, void *context); + +/****f* silcutil/SilcThreadAPI/silc_thread_pool_alloc + * + * SYNOPSIS + * + * SilcThreadPool silc_thread_pool_alloc(SilcStack stack, + * SilcUInt32 min_threads, + * SilcUInt32 max_threads, + * SilcBool start_min_threads); + * + * DESCRIPTION + * + * Allocate thread pool with at least `min_threads' and at most + * `max_threads' many threads. If `start_min_threads' is TRUE this will + * start `min_threads' many threads immediately. Returns the thread + * pool context or NULL on error. If `stack' is non-NULL memory is + * allocated from `stack'. When the thread pool is freed the memory + * is returned to `stack'. + * + * EXAMPLE + * + * // Start thread pool, by default it has 0 threads. + * pool = silc_thread_pool_alloc(NULL, 0, 5, FALSE); + * + * // Function to execute in a thread + * void my_func(SilcSchedule schedule, void *context) + * { + * MyContext mycontext = context; + * ... + * } + * + * // Execute code in a thread in the pool + * silc_thread_pool_run(pool, TRUE, NULL, my_func, my_context, NULL, NULL); + * + ***/ +SilcThreadPool silc_thread_pool_alloc(SilcStack stack, + SilcUInt32 min_threads, + SilcUInt32 max_threads, + SilcBool start_min_threads); + +/****f* silcutil/SilcThreadAPI/silc_thread_pool_free + * + * SYNOPSIS + * + * void silc_thread_pool_free(SilcThreadPool tp, SilcBool wait_unfinished); + * + * DESCRIPTION + * + * Free the thread pool. If `wait_unfinished' is TRUE this will block + * and waits that all remaining active threads finish before freeing + * the pool. + * + ***/ +void silc_thread_pool_free(SilcThreadPool tp, SilcBool wait_unfinished); + +/****f* silcutil/SilcThreadAPI/silc_thread_pool_run + * + * SYNOPSIS + * + * SilcBool silc_thread_pool_run(SilcThreadPool tp, + * SilcBool queueable, + * SilcSchedule schedule, + * SilcThreadPoolFunc run, + * void *run_context, + * SilcTaskCallback completion, + * void *completion_context); + * + * DESCRIPTION + * + * Run the `run' function with `run_context' in one of the threads in the + * thread pool. Returns FALSE if the thread pool is being freed. If + * there are no free threads left in the pool this will queue the `run' + * and call it once a thread becomes free, if `queueable' is TRUE. If + * `queueable' is FALSE and there are no free threads, this returns FALSE + * and `run' is not executed. + * + * If `completion' is non-NULL it will be called to indicate completion + * of the `run' function. If `schedule' is non-NULL the `completion' + * will be called through the scheduler in the main thread. If it is + * NULL the `completion' is called directly from the thread after the + * `run' has returned. + * + ***/ +SilcBool silc_thread_pool_run(SilcThreadPool tp, + SilcBool queue, + SilcSchedule schedule, + SilcThreadPoolFunc run, + void *run_context, + SilcTaskCallback completion, + void *completion_context); + +/****f* silcutil/SilcThreadAPI/silc_thread_pool_set_max_threads + * + * SYNOPSIS + * + * void silc_thread_pool_set_max_threads(SilcThreadPool tp, + * SilcUInt32 max_threads); + * + * DESCRIPTION + * + * Modify the amount of maximum threads of the pool. This call does not + * affect any currently active or running thread. + * + ***/ +void silc_thread_pool_set_max_threads(SilcThreadPool tp, + SilcUInt32 max_threads); + +/****f* silcutil/SilcThreadAPI/silc_thread_pool_get_max_threads + * + * SYNOPSIS + * + * SilcUInt32 silc_thread_pool_get_max_threads(SilcThreadPool tp); + * + * DESCRIPTION + * + * Returns the number of maximum threads to which the pool can grow. + * + ***/ +SilcUInt32 silc_thread_pool_get_max_threads(SilcThreadPool tp); + +/****f* silcutil/SilcThreadAPI/silc_thread_pool_num_free_threads + * + * SYNOPSIS + * + * SilcUInt32 silc_thread_pool_num_free_threads(SilcThreadPool tp); + * + * DESCRIPTION + * + * Returns the number of free threads in the pool currently. Free threads + * are threads that are not currently executing any code. + * + ***/ +SilcUInt32 silc_thread_pool_num_free_threads(SilcThreadPool tp); + +/****f* silcutil/SilcThreadAPI/silc_thread_pool_purge + * + * SYNOPSIS + * + * void silc_thread_pool_purge(SilcThreadPool tp); + * + * DESCRIPTION + * + * Stops all free and started threads. The minumum amount of threads + * specified to silc_thread_pool_alloc always remains. Any thread that + * is currently executing code is not affected by this call. + * + ***/ +void silc_thread_pool_purge(SilcThreadPool tp); + +/****f* silcutil/SilcThreadAPI/silc_thread_tls_set + * + * SYNOPSIS + * + * void silc_thread_tls_set(void *context); + * + * DESCRIPTION + * + * Sets `context' into the Thread-local storage. Any previously set + * value will be replaced. This function may be called for the main + * thread also. This function may be called also if the program does + * not support threads. + * + * To retrieve the context from the Tls, call silc_thread_tls_get. + * + ***/ +void silc_thread_tls_set(void *context); + +/****f* silcutil/SilcThreadAPI/silc_thread_tls_get + * + * SYNOPSIS + * + * void *silc_thread_tls_get(void); + * + * DESCRIPTION + * + * Returns context from the Thread-local storage. If context has no been + * set for the current thread NULL will be returned. + * + ***/ +void *silc_thread_tls_get(void); + +#include "silcthread_i.h" + #endif