5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2008 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silcutil/Thread Queue Interface
24 * This interface provides asynchronous thread queues that can be used to
25 * pass messages and data between two or more threads. Typically a thread
26 * would create the queue, push data into the queue and some other thread
27 * takes the data from the queue or blocks until more data is available
34 * // Create queue and push data into it
35 * SilcThreadQueue queue = silc_thread_queue_alloc();
36 * silc_thread_queue_push(queue, data);
40 * // Connect to the queue
41 * silc_thread_queue_connect(queue);
43 * // Block here until data is available from the queue
44 * data = silc_thread_queue_pop(queue, TRUE);
48 #ifndef SILCTHREADQUEUE_H
49 #define SILCTHREADQUEUE_H
51 /****s* silcutil/SilcThreadQueue
55 * typedef struct SilcThreadQueueStruct *SilcThreadQueue;
59 * The thread queue context allocated by silc_thread_queue_alloc and
60 * given as argument to all silc_thread_queue_* functions.
63 typedef struct SilcThreadQueueStruct *SilcThreadQueue;
65 /****f* silcutil/silc_thread_queue_alloc
69 * SilcThreadQueue silc_thread_queue_alloc(void);
73 * Allocates new thread queue context and returns it. Returns NULL in
74 * case of error and sets the silc_errno. The returned context is
75 * immediately ready to be used. For a thread to be able to use the
76 * queue it must first connect to it by calling silc_thread_queue_connect.
77 * The thread that creates the queue automatically connects to the queue.
80 SilcThreadQueue silc_thread_queue_alloc(void);
82 /****f* silcutil/silc_thread_queue_connect
86 * SilcBool silc_thread_queue_connect(SilcThreadQueue queue);
90 * Connects current thread to the thread queue. This function must
91 * be called by each thread wanting to use the thread queue. After the
92 * thread is finished using the queue it must disconnect from the queue
93 * by calling silc_thread_queue_disconnect.
96 void silc_thread_queue_connect(SilcThreadQueue queue);
98 /****f* silcutil/silc_thread_queue_disconnect
102 * void silc_thread_queue_disconnect(SilcThreadQueue queue);
106 * Disconnects the current thread from the thread queue. This must be
107 * called after the thread has finished using the thread queue.
109 * When the last thread has disconnected from the queue the queue is
113 void silc_thread_queue_disconnect(SilcThreadQueue queue);
115 /****f* silcutil/silc_thread_queue_push
119 * void silc_thread_queue_push(SilcThreadQueue queue, void *data);
123 * Pushes the `data' into the thread queue. The data will become
124 * immediately available in the queue for other threads.
127 void silc_thread_queue_push(SilcThreadQueue queue, void *data);
129 /****f* silcutil/silc_thread_queue_pop
133 * void *silc_thread_queue_pop(SilcThreadQueue queue, SilcBool block);
137 * Takes data from the queue and returns it. If `block' is TRUE and
138 * data is not available this will block until data becomes available.
139 * If `block' is FALSE and data is not available this will return NULL.
140 * If `block' is TRUE this will never return NULL.
143 void *silc_thread_queue_pop(SilcThreadQueue queue, SilcBool block);
145 /****f* silcutil/silc_thread_queue_timed_pop
149 * void *silc_thread_queue_timed_pop(SilcThreadQueue queue,
154 * Takes data from the thread queue or waits at most `timeout_msec'
155 * milliseconds for the data to arrive. If data is not available when
156 * the timeout occurrs this returns NULL.
159 void *silc_thread_queue_timed_pop(SilcThreadQueue queue,
162 /****f* silcutil/silc_thread_queue_pop_list
166 * SilcDList silc_thread_queue_pop_list(SilcThreadQueue queue,
171 * Takes everything from the queue and returns the data in a list. The
172 * caller must free the returned list with silc_dlist_uninit. If the
173 * `block' is FALSE this will never block but will return the queue
174 * immediately. If `block' is TRUE this will block if the queue is
178 SilcDList silc_thread_queue_pop_list(SilcThreadQueue queue, SilcBool block);
180 #endif /* SILCTHREADQUEUE_H */