X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilcutil%2Fsilcthread.h;h=5afc0a03201cced36b4b3cd48fd75fcb81c830b8;hb=e7b6c157b80152bf9fb9266e6bdd93f9fb0db776;hp=5d4932d8fb574e8284178ba1176a7137624c44c0;hpb=2971471c6955c1217921700290624d4cb3ed303e;p=silc.git diff --git a/lib/silcutil/silcthread.h b/lib/silcutil/silcthread.h index 5d4932d8..5afc0a03 100644 --- a/lib/silcutil/silcthread.h +++ b/lib/silcutil/silcthread.h @@ -1,43 +1,51 @@ -/****h* silcutil/silcthread.h - * - * NAME - * - * silcmutex.h - * - * COPYRIGHT - * - * Author: Pekka Riikonen - * - * Copyright (C) 2001 Pekka Riikonen +/* + + silcmutex.h + + Author: 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 + the Free Software Foundation; version 2 of the License. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + +*/ + +/****h* silcutil/SILC Thread Interface * - * 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 - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. + * DESCRIPTION * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. + * 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. * - * DESCRIPTION + * 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. * - * Interface for SILC Thread implementation. This is platform independent - * implementation of threads for applications needing concurrent execution - * with the application's main thread. The threads created with this - * interface executes concurrently with the calling thread. + * 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 * * NAME - * + * * typedef struct SilcThreadStruct *SilcThread; * * DESCRIPTION @@ -72,8 +80,8 @@ typedef void *(*SilcThreadStart)(void *context); * * SYNOPSIS * - * SilcThread silc_thread_create(SilcThreadStart start_func, void *context); - * + * SilcThread silc_thread_create(SilcThreadStart start_func, + * void *context, SilcBool waitable); * DESCRIPTION * * Creates a new thread. The `start_func' with `context' will be @@ -93,9 +101,13 @@ 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, - bool waitable); + SilcBool waitable); /****f* silcutil/SilcThreadAPI/silc_thread_exit * @@ -122,7 +134,7 @@ void silc_thread_exit(void *exit_value); * * DESCRIPTION * - * Returns a pointer of the current thread. + * Returns a pointer to the current thread. * ***/ SilcThread silc_thread_self(void); @@ -131,7 +143,7 @@ SilcThread silc_thread_self(void); * * SYNOPSIS * - * bool silc_thread_wait(SilcThread thread, void **exit_value); + * SilcBool silc_thread_wait(SilcThread thread, void **exit_value); * * DESCRIPTION * @@ -143,6 +155,235 @@ SilcThread silc_thread_self(void); * FALSE value. * ***/ -bool silc_thread_wait(SilcThread thread, void **exit_value); +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