← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjlib/include/pj/ioqueue.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/pjlib/include/pj/ioqueue.h
1
 
/* $Id: ioqueue.h 3553 2011-05-05 06:14:19Z nanang $
2
 
 */
3
 
/*
4
 
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
5
 
 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
6
 
 *
7
 
 * This program is free software; you can redistribute it and/or modify
8
 
 * it under the terms of the GNU General Public License as published by
9
 
 * the Free Software Foundation; either version 2 of the License, or
10
 
 * (at your option) any later version.
11
 
 *
12
 
 * This program is distributed in the hope that it will be useful,
13
 
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14
 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15
 
 * GNU General Public License for more details.
16
 
 *
17
 
 * You should have received a copy of the GNU General Public License
18
 
 * along with this program; if not, write to the Free Software
19
 
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
20
 
 */
21
 
#ifndef __PJ_IOQUEUE_H__
22
 
#define __PJ_IOQUEUE_H__
23
 
 
24
 
/**
25
 
 * @file ioqueue.h
26
 
 * @brief I/O Dispatching Mechanism
27
 
 */
28
 
 
29
 
#include <pj/types.h>
30
 
 
31
 
PJ_BEGIN_DECL
32
 
 
33
 
/**
34
 
 * @defgroup PJ_IO Input/Output
35
 
 * @brief Input/Output
36
 
 * @ingroup PJ_OS
37
 
 *
38
 
 * This section contains API building blocks to perform network I/O and
39
 
 * communications. If provides:
40
 
 *  - @ref PJ_SOCK
41
 
 *\n
42
 
 *    A highly portable socket abstraction, runs on all kind of
43
 
 *    network APIs such as standard BSD socket, Windows socket, Linux
44
 
 *    \b kernel socket, PalmOS networking API, etc.
45
 
 *
46
 
 *  - @ref pj_addr_resolve
47
 
 *\n
48
 
 *    Portable address resolution, which implements #pj_gethostbyname().
49
 
 *
50
 
 *  - @ref PJ_SOCK_SELECT
51
 
 *\n
52
 
 *    A portable \a select() like API (#pj_sock_select()) which can be
53
 
 *    implemented with various back-ends.
54
 
 *
55
 
 *  - @ref PJ_IOQUEUE
56
 
 *\n
57
 
 *    Framework for dispatching network events.
58
 
 *
59
 
 * For more information see the modules below.
60
 
 */
61
 
 
62
 
/**
63
 
 * @defgroup PJ_IOQUEUE IOQueue: I/O Event Dispatching with Proactor Pattern
64
 
 * @ingroup PJ_IO
65
 
 * @{
66
 
 *
67
 
 * I/O Queue provides API for performing asynchronous I/O operations. It
68
 
 * conforms to proactor pattern, which allows application to submit an
69
 
 * asynchronous operation and to be notified later when the operation has
70
 
 * completed.
71
 
 *
72
 
 * The I/O Queue can work on both socket and file descriptors. For
73
 
 * asynchronous file operations however, one must make sure that the correct
74
 
 * file I/O back-end is used, because not all file I/O back-end can be
75
 
 * used with the ioqueue. Please see \ref PJ_FILE_IO for more details.
76
 
 *
77
 
 * The framework works natively in platforms where asynchronous operation API
78
 
 * exists, such as in Windows NT with IoCompletionPort/IOCP. In other
79
 
 * platforms, the I/O queue abstracts the operating system's event poll API
80
 
 * to provide semantics similar to IoCompletionPort with minimal penalties
81
 
 * (i.e. per ioqueue and per handle mutex protection).
82
 
 *
83
 
 * The I/O queue provides more than just unified abstraction. It also:
84
 
 *  - makes sure that the operation uses the most effective way to utilize
85
 
 *    the underlying mechanism, to achieve the maximum theoritical
86
 
 *    throughput possible on a given platform.
87
 
 *  - choose the most efficient mechanism for event polling on a given
88
 
 *    platform.
89
 
 *
90
 
 * Currently, the I/O Queue is implemented using:
91
 
 *  - <tt><b>select()</b></tt>, as the common denominator, but the least
92
 
 *    efficient. Also the number of descriptor is limited to
93
 
 *    \c PJ_IOQUEUE_MAX_HANDLES (which by default is 64).
94
 
 *  - <tt><b>/dev/epoll</b></tt> on Linux (user mode and kernel mode),
95
 
 *    a much faster replacement for select() on Linux (and more importantly
96
 
 *    doesn't have limitation on number of descriptors).
97
 
 *  - <b>I/O Completion ports</b> on Windows NT/2000/XP, which is the most
98
 
 *    efficient way to dispatch events in Windows NT based OSes, and most
99
 
 *    importantly, it doesn't have the limit on how many handles to monitor.
100
 
 *    And it works with files (not only sockets) as well.
101
 
 *
102
 
 *
103
 
 * \section pj_ioqueue_concurrency_sec Concurrency Rules
104
 
 *
105
 
 * The ioqueue has been fine tuned to allow multiple threads to poll the
106
 
 * handles simultaneously, to maximize scalability when the application is
107
 
 * running on multiprocessor systems. When more than one threads are polling
108
 
 * the ioqueue and there are more than one handles are signaled, more than
109
 
 * one threads will execute the callback simultaneously to serve the events.
110
 
 * These parallel executions are completely safe when the events happen for
111
 
 * two different handles.
112
 
 *
113
 
 * However, with multithreading, care must be taken when multiple events
114
 
 * happen on the same handle, or when event is happening on a handle (and
115
 
 * the callback is being executed) and application is performing
116
 
 * unregistration to the handle at the same time.
117
 
 *
118
 
 * The treatments of above scenario differ according to the concurrency
119
 
 * setting that are applied to the handle.
120
 
 *
121
 
 * \subsection pj_ioq_concur_set Concurrency Settings for Handles
122
 
 *
123
 
 * Concurrency can be set on per handle (key) basis, by using
124
 
 * #pj_ioqueue_set_concurrency() function. The default key concurrency value
125
 
 * for the handle is inherited from the key concurrency setting of the ioqueue,
126
 
 * and the key concurrency setting for the ioqueue can be changed by using
127
 
 * #pj_ioqueue_set_default_concurrency(). The default key concurrency setting
128
 
 * for ioqueue itself is controlled by compile time setting
129
 
 * PJ_IOQUEUE_DEFAULT_ALLOW_CONCURRENCY.
130
 
 *
131
 
 * Note that this key concurrency setting only controls whether multiple
132
 
 * threads are allowed to operate <b>on the same key</b> at the same time.
133
 
 * The ioqueue itself always allows multiple threads to enter the ioqeuue at
134
 
 * the same time, and also simultaneous callback calls to <b>differrent
135
 
 * keys</b> is always allowed regardless to the key concurrency setting.
136
 
 *
137
 
 * \subsection pj_ioq_parallel Parallel Callback Executions for the Same Handle
138
 
 *
139
 
 * Note that when key concurrency is enabled (i.e. parallel callback calls on
140
 
 * the same key is allowed; this is the default setting), the ioqueue will only
141
 
 * perform simultaneous callback executions on the same key when the key has
142
 
 * invoked multiple pending operations. This could be done for example by
143
 
 * calling #pj_ioqueue_recvfrom() more than once on the same key, each with
144
 
 * the same key but different operation key (pj_ioqueue_op_key_t). With this
145
 
 * scenario, when multiple packets arrive on the key at the same time, more
146
 
 * than one threads may execute the callback simultaneously, each with the
147
 
 * same key but different operation key.
148
 
 *
149
 
 * When there is only one pending operation on the key (e.g. there is only one
150
 
 * #pj_ioqueue_recvfrom() invoked on the key), then events occuring to the
151
 
 * same key will be queued by the ioqueue, thus no simultaneous callback calls
152
 
 * will be performed.
153
 
 *
154
 
 * \subsection pj_ioq_allow_concur Concurrency is Enabled (Default Value)
155
 
 *
156
 
 * The default setting for the ioqueue is to allow multiple threads to
157
 
 * execute callbacks for the same handle/key. This setting is selected to
158
 
 * promote good performance and scalability for application.
159
 
 *
160
 
 * However this setting has a major drawback with regard to synchronization,
161
 
 * and application MUST carefully follow the following guidelines to ensure
162
 
 * that parallel access to the key does not cause problems:
163
 
 *
164
 
 *  - Always note that callback may be called simultaneously for the same
165
 
 *    key.
166
 
 *  - <b>Care must be taken when unregistering a key</b> from the
167
 
 *    ioqueue. Application must take care that when one thread is issuing
168
 
 *    an unregistration, other thread is not simultaneously invoking the
169
 
 *    callback <b>to the same key</b>.
170
 
 *\n
171
 
 *    This happens because the ioqueue functions are working with a pointer
172
 
 *    to the key, and there is a possible race condition where the pointer
173
 
 *    has been rendered invalid by other threads before the ioqueue has a
174
 
 *    chance to acquire mutex on it.
175
 
 *
176
 
 * \subsection pj_ioq_disallow_concur Concurrency is Disabled
177
 
 *
178
 
 * Alternatively, application may disable key concurrency to make
179
 
 * synchronization easier. As noted above, there are three ways to control
180
 
 * key concurrency setting:
181
 
 *  - by controlling on per handle/key basis, with #pj_ioqueue_set_concurrency().
182
 
 *  - by changing default key concurrency setting on the ioqueue, with
183
 
 *    #pj_ioqueue_set_default_concurrency().
184
 
 *  - by changing the default concurrency on compile time, by declaring
185
 
 *    PJ_IOQUEUE_DEFAULT_ALLOW_CONCURRENCY macro to zero in your config_site.h
186
 
 *
187
 
 * \section pj_ioqeuue_examples_sec Examples
188
 
 *
189
 
 * For some examples on how to use the I/O Queue, please see:
190
 
 *
191
 
 *  - \ref page_pjlib_ioqueue_tcp_test
192
 
 *  - \ref page_pjlib_ioqueue_udp_test
193
 
 *  - \ref page_pjlib_ioqueue_perf_test
194
 
 */
195
 
 
196
 
 
197
 
/**
198
 
 * This structure describes operation specific key to be submitted to
199
 
 * I/O Queue when performing the asynchronous operation. This key will
200
 
 * be returned to the application when completion callback is called.
201
 
 *
202
 
 * Application normally wants to attach it's specific data in the
203
 
 * \c user_data field so that it can keep track of which operation has
204
 
 * completed when the callback is called. Alternatively, application can
205
 
 * also extend this struct to include its data, because the pointer that
206
 
 * is returned in the completion callback will be exactly the same as
207
 
 * the pointer supplied when the asynchronous function is called.
208
 
 */
209
 
typedef struct pj_ioqueue_op_key_t
210
 
{
211
 
    void *internal__[32];           /**< Internal I/O Queue data.   */
212
 
    void *activesock_data;          /**< Active socket data.        */
213
 
    void *user_data;                /**< Application data.          */
214
 
} pj_ioqueue_op_key_t;
215
 
 
216
 
/**
217
 
 * This structure describes the callbacks to be called when I/O operation
218
 
 * completes.
219
 
 */
220
 
typedef struct pj_ioqueue_callback
221
 
{
222
 
    /**
223
 
     * This callback is called when #pj_ioqueue_recv or #pj_ioqueue_recvfrom
224
 
     * completes.
225
 
     *
226
 
     * @param key           The key.
227
 
     * @param op_key        Operation key.
228
 
     * @param bytes_read    >= 0 to indicate the amount of data read,
229
 
     *                      otherwise negative value containing the error
230
 
     *                      code. To obtain the pj_status_t error code, use
231
 
     *                      (pj_status_t code = -bytes_read).
232
 
     */
233
 
    void (*on_read_complete)(pj_ioqueue_key_t *key,
234
 
                             pj_ioqueue_op_key_t *op_key,
235
 
                             pj_ssize_t bytes_read);
236
 
 
237
 
    /**
238
 
     * This callback is called when #pj_ioqueue_send or #pj_ioqueue_sendto
239
 
     * completes.
240
 
     *
241
 
     * @param key           The key.
242
 
     * @param op_key        Operation key.
243
 
     * @param bytes_sent    >= 0 to indicate the amount of data written,
244
 
     *                      otherwise negative value containing the error
245
 
     *                      code. To obtain the pj_status_t error code, use
246
 
     *                      (pj_status_t code = -bytes_sent).
247
 
     */
248
 
    void (*on_write_complete)(pj_ioqueue_key_t *key,
249
 
                              pj_ioqueue_op_key_t *op_key,
250
 
                              pj_ssize_t bytes_sent);
251
 
 
252
 
    /**
253
 
     * This callback is called when #pj_ioqueue_accept completes.
254
 
     *
255
 
     * @param key           The key.
256
 
     * @param op_key        Operation key.
257
 
     * @param sock          Newly connected socket.
258
 
     * @param status        Zero if the operation completes successfully.
259
 
     */
260
 
    void (*on_accept_complete)(pj_ioqueue_key_t *key,
261
 
                               pj_ioqueue_op_key_t *op_key,
262
 
                               pj_sock_t sock,
263
 
                               pj_status_t status);
264
 
 
265
 
    /**
266
 
     * This callback is called when #pj_ioqueue_connect completes.
267
 
     *
268
 
     * @param key           The key.
269
 
     * @param status        PJ_SUCCESS if the operation completes successfully.
270
 
     */
271
 
    void (*on_connect_complete)(pj_ioqueue_key_t *key,
272
 
                                pj_status_t status);
273
 
} pj_ioqueue_callback;
274
 
 
275
 
 
276
 
/**
277
 
 * Types of pending I/O Queue operation. This enumeration is only used
278
 
 * internally within the ioqueue.
279
 
 */
280
 
typedef enum pj_ioqueue_operation_e
281
 
{
282
 
    PJ_IOQUEUE_OP_NONE          = 0,    /**< No operation.          */
283
 
    PJ_IOQUEUE_OP_READ          = 1,    /**< read() operation.      */
284
 
    PJ_IOQUEUE_OP_RECV          = 2,    /**< recv() operation.      */
285
 
    PJ_IOQUEUE_OP_RECV_FROM     = 4,    /**< recvfrom() operation.  */
286
 
    PJ_IOQUEUE_OP_WRITE         = 8,    /**< write() operation.     */
287
 
    PJ_IOQUEUE_OP_SEND          = 16,   /**< send() operation.      */
288
 
    PJ_IOQUEUE_OP_SEND_TO       = 32,   /**< sendto() operation.    */
289
 
#if defined(PJ_HAS_TCP) && PJ_HAS_TCP != 0
290
 
    PJ_IOQUEUE_OP_ACCEPT        = 64,   /**< accept() operation.    */
291
 
    PJ_IOQUEUE_OP_CONNECT       = 128   /**< connect() operation.   */
292
 
#endif  /* PJ_HAS_TCP */
293
 
} pj_ioqueue_operation_e;
294
 
 
295
 
 
296
 
/**
297
 
 * This macro specifies the maximum number of events that can be
298
 
 * processed by the ioqueue on a single poll cycle, on implementation
299
 
 * that supports it. The value is only meaningfull when specified
300
 
 * during PJLIB build.
301
 
 */
302
 
#ifndef PJ_IOQUEUE_MAX_EVENTS_IN_SINGLE_POLL
303
 
#   define PJ_IOQUEUE_MAX_EVENTS_IN_SINGLE_POLL     (16)
304
 
#endif
305
 
 
306
 
/**
307
 
 * When this flag is specified in ioqueue's recv() or send() operations,
308
 
 * the ioqueue will always mark the operation as asynchronous.
309
 
 */
310
 
#define PJ_IOQUEUE_ALWAYS_ASYNC     ((pj_uint32_t)1 << (pj_uint32_t)31)
311
 
 
312
 
/**
313
 
 * Return the name of the ioqueue implementation.
314
 
 *
315
 
 * @return              Implementation name.
316
 
 */
317
 
PJ_DECL(const char*) pj_ioqueue_name(void);
318
 
 
319
 
 
320
 
/**
321
 
 * Create a new I/O Queue framework.
322
 
 *
323
 
 * @param pool          The pool to allocate the I/O queue structure.
324
 
 * @param max_fd        The maximum number of handles to be supported, which
325
 
 *                      should not exceed PJ_IOQUEUE_MAX_HANDLES.
326
 
 * @param ioqueue       Pointer to hold the newly created I/O Queue.
327
 
 *
328
 
 * @return              PJ_SUCCESS on success.
329
 
 */
330
 
PJ_DECL(pj_status_t) pj_ioqueue_create( pj_pool_t *pool,
331
 
                                        pj_size_t max_fd,
332
 
                                        pj_ioqueue_t **ioqueue);
333
 
 
334
 
/**
335
 
 * Destroy the I/O queue.
336
 
 *
337
 
 * @param ioque         The I/O Queue to be destroyed.
338
 
 *
339
 
 * @return              PJ_SUCCESS if success.
340
 
 */
341
 
PJ_DECL(pj_status_t) pj_ioqueue_destroy( pj_ioqueue_t *ioque );
342
 
 
343
 
/**
344
 
 * Set the lock object to be used by the I/O Queue. This function can only
345
 
 * be called right after the I/O queue is created, before any handle is
346
 
 * registered to the I/O queue.
347
 
 *
348
 
 * Initially the I/O queue is created with non-recursive mutex protection.
349
 
 * Applications can supply alternative lock to be used by calling this
350
 
 * function.
351
 
 *
352
 
 * @param ioque         The ioqueue instance.
353
 
 * @param lock          The lock to be used by the ioqueue.
354
 
 * @param auto_delete   In non-zero, the lock will be deleted by the ioqueue.
355
 
 *
356
 
 * @return              PJ_SUCCESS or the appropriate error code.
357
 
 */
358
 
PJ_DECL(pj_status_t) pj_ioqueue_set_lock( pj_ioqueue_t *ioque,
359
 
                                          pj_lock_t *lock,
360
 
                                          pj_bool_t auto_delete );
361
 
 
362
 
/**
363
 
 * Set default concurrency policy for this ioqueue. If this function is not
364
 
 * called, the default concurrency policy for the ioqueue is controlled by
365
 
 * compile time setting PJ_IOQUEUE_DEFAULT_ALLOW_CONCURRENCY.
366
 
 *
367
 
 * Note that changing the concurrency setting to the ioqueue will only affect
368
 
 * subsequent key registrations. To modify the concurrency setting for
369
 
 * individual key, use #pj_ioqueue_set_concurrency().
370
 
 *
371
 
 * @param ioqueue       The ioqueue instance.
372
 
 * @param allow         Non-zero to allow concurrent callback calls, or
373
 
 *                      PJ_FALSE to disallow it.
374
 
 *
375
 
 * @return              PJ_SUCCESS on success or the appropriate error code.
376
 
 */
377
 
PJ_DECL(pj_status_t) pj_ioqueue_set_default_concurrency(pj_ioqueue_t *ioqueue,
378
 
                                                        pj_bool_t allow);
379
 
 
380
 
/**
381
 
 * Register a socket to the I/O queue framework.
382
 
 * When a socket is registered to the IOQueue, it may be modified to use
383
 
 * non-blocking IO. If it is modified, there is no guarantee that this
384
 
 * modification will be restored after the socket is unregistered.
385
 
 *
386
 
 * @param pool      To allocate the resource for the specified handle,
387
 
 *                  which must be valid until the handle/key is unregistered
388
 
 *                  from I/O Queue.
389
 
 * @param ioque     The I/O Queue.
390
 
 * @param sock      The socket.
391
 
 * @param user_data User data to be associated with the key, which can be
392
 
 *                  retrieved later.
393
 
 * @param cb        Callback to be called when I/O operation completes.
394
 
 * @param key       Pointer to receive the key to be associated with this
395
 
 *                  socket. Subsequent I/O queue operation will need this
396
 
 *                  key.
397
 
 *
398
 
 * @return          PJ_SUCCESS on success, or the error code.
399
 
 */
400
 
PJ_DECL(pj_status_t) pj_ioqueue_register_sock( pj_pool_t *pool,
401
 
                                               pj_ioqueue_t *ioque,
402
 
                                               pj_sock_t sock,
403
 
                                               void *user_data,
404
 
                                               const pj_ioqueue_callback *cb,
405
 
                                               pj_ioqueue_key_t **key );
406
 
 
407
 
/**
408
 
 * Unregister from the I/O Queue framework. Caller must make sure that
409
 
 * the key doesn't have any pending operations before calling this function,
410
 
 * by calling #pj_ioqueue_is_pending() for all previously submitted
411
 
 * operations except asynchronous connect, and if necessary call
412
 
 * #pj_ioqueue_post_completion() to cancel the pending operations.
413
 
 *
414
 
 * Note that asynchronous connect operation will automatically be
415
 
 * cancelled during the unregistration.
416
 
 *
417
 
 * Also note that when I/O Completion Port backend is used, application
418
 
 * MUST close the handle immediately after unregistering the key. This is
419
 
 * because there is no unregistering API for IOCP. The only way to
420
 
 * unregister the handle from IOCP is to close the handle.
421
 
 *
422
 
 * @param key       The key that was previously obtained from registration.
423
 
 *
424
 
 * @return          PJ_SUCCESS on success or the error code.
425
 
 *
426
 
 * @see pj_ioqueue_is_pending
427
 
 */
428
 
PJ_DECL(pj_status_t) pj_ioqueue_unregister( pj_ioqueue_key_t *key );
429
 
 
430
 
 
431
 
/**
432
 
 * Get user data associated with an ioqueue key.
433
 
 *
434
 
 * @param key       The key that was previously obtained from registration.
435
 
 *
436
 
 * @return          The user data associated with the descriptor, or NULL
437
 
 *                  on error or if no data is associated with the key during
438
 
 *                  registration.
439
 
 */
440
 
PJ_DECL(void*) pj_ioqueue_get_user_data( pj_ioqueue_key_t *key );
441
 
 
442
 
/**
443
 
 * Set or change the user data to be associated with the file descriptor or
444
 
 * handle or socket descriptor.
445
 
 *
446
 
 * @param key       The key that was previously obtained from registration.
447
 
 * @param user_data User data to be associated with the descriptor.
448
 
 * @param old_data  Optional parameter to retrieve the old user data.
449
 
 *
450
 
 * @return          PJ_SUCCESS on success or the error code.
451
 
 */
452
 
PJ_DECL(pj_status_t) pj_ioqueue_set_user_data( pj_ioqueue_key_t *key,
453
 
                                               void *user_data,
454
 
                                               void **old_data);
455
 
 
456
 
/**
457
 
 * Configure whether the ioqueue is allowed to call the key's callback
458
 
 * concurrently/in parallel. The default concurrency setting for the key
459
 
 * is controlled by ioqueue's default concurrency value, which can be
460
 
 * changed by calling #pj_ioqueue_set_default_concurrency().
461
 
 *
462
 
 * If concurrency is allowed for the key, it means that if there are more
463
 
 * than one pending operations complete simultaneously, more than one
464
 
 * threads may call the key's  callback at the same time. This generally
465
 
 * would promote good scalability for application, at the expense of more
466
 
 * complexity to manage the concurrent accesses in application's code.
467
 
 *
468
 
 * Alternatively application may disable the concurrent access by
469
 
 * setting the \a allow flag to false. With concurrency disabled, only
470
 
 * one thread can call the key's callback at one time.
471
 
 *
472
 
 * @param key       The key that was previously obtained from registration.
473
 
 * @param allow     Set this to non-zero to allow concurrent callback calls
474
 
 *                  and zero (PJ_FALSE) to disallow it.
475
 
 *
476
 
 * @return          PJ_SUCCESS on success or the appropriate error code.
477
 
 */
478
 
PJ_DECL(pj_status_t) pj_ioqueue_set_concurrency(pj_ioqueue_key_t *key,
479
 
                                                pj_bool_t allow);
480
 
 
481
 
/**
482
 
 * Acquire the key's mutex. When the key's concurrency is disabled,
483
 
 * application may call this function to synchronize its operation
484
 
 * with the key's callback (i.e. this function will block until the
485
 
 * key's callback returns).
486
 
 *
487
 
 * @param key       The key that was previously obtained from registration.
488
 
 *
489
 
 * @return          PJ_SUCCESS on success or the appropriate error code.
490
 
 */
491
 
PJ_DECL(pj_status_t) pj_ioqueue_lock_key(pj_ioqueue_key_t *key);
492
 
 
493
 
/**
494
 
 * Release the lock previously acquired with pj_ioqueue_lock_key().
495
 
 *
496
 
 * @param key       The key that was previously obtained from registration.
497
 
 *
498
 
 * @return          PJ_SUCCESS on success or the appropriate error code.
499
 
 */
500
 
PJ_DECL(pj_status_t) pj_ioqueue_unlock_key(pj_ioqueue_key_t *key);
501
 
 
502
 
/**
503
 
 * Initialize operation key.
504
 
 *
505
 
 * @param op_key    The operation key to be initialied.
506
 
 * @param size      The size of the operation key.
507
 
 */
508
 
PJ_DECL(void) pj_ioqueue_op_key_init( pj_ioqueue_op_key_t *op_key,
509
 
                                      pj_size_t size );
510
 
 
511
 
/**
512
 
 * Check if operation is pending on the specified operation key.
513
 
 * The \c op_key must have been initialized with #pj_ioqueue_op_key_init()
514
 
 * or submitted as pending operation before, or otherwise the result
515
 
 * is undefined.
516
 
 *
517
 
 * @param key       The key.
518
 
 * @param op_key    The operation key, previously submitted to any of
519
 
 *                  the I/O functions and has returned PJ_EPENDING.
520
 
 *
521
 
 * @return          Non-zero if operation is still pending.
522
 
 */
523
 
PJ_DECL(pj_bool_t) pj_ioqueue_is_pending( pj_ioqueue_key_t *key,
524
 
                                          pj_ioqueue_op_key_t *op_key );
525
 
 
526
 
 
527
 
/**
528
 
 * Post completion status to the specified operation key and call the
529
 
 * appropriate callback. When the callback is called, the number of bytes
530
 
 * received in read/write callback or the status in accept/connect callback
531
 
 * will be set from the \c bytes_status parameter.
532
 
 *
533
 
 * @param key           The key.
534
 
 * @param op_key        Pending operation key.
535
 
 * @param bytes_status  Number of bytes or status to be set. A good value
536
 
 *                      to put here is -PJ_ECANCELLED.
537
 
 *
538
 
 * @return              PJ_SUCCESS if completion status has been successfully
539
 
 *                      sent.
540
 
 */
541
 
PJ_DECL(pj_status_t) pj_ioqueue_post_completion( pj_ioqueue_key_t *key,
542
 
                                                 pj_ioqueue_op_key_t *op_key,
543
 
                                                 pj_ssize_t bytes_status );
544
 
 
545
 
 
546
 
 
547
 
#if defined(PJ_HAS_TCP) && PJ_HAS_TCP != 0
548
 
/**
549
 
 * Instruct I/O Queue to accept incoming connection on the specified
550
 
 * listening socket. This function will return immediately (i.e. non-blocking)
551
 
 * regardless whether a connection is immediately available. If the function
552
 
 * can't complete immediately, the caller will be notified about the incoming
553
 
 * connection when it calls pj_ioqueue_poll(). If a new connection is
554
 
 * immediately available, the function returns PJ_SUCCESS with the new
555
 
 * connection; in this case, the callback WILL NOT be called.
556
 
 *
557
 
 * @param key       The key which registered to the server socket.
558
 
 * @param op_key    An operation specific key to be associated with the
559
 
 *                  pending operation, so that application can keep track of
560
 
 *                  which operation has been completed when the callback is
561
 
 *                  called.
562
 
 * @param new_sock  Argument which contain pointer to receive the new socket
563
 
 *                  for the incoming connection.
564
 
 * @param local     Optional argument which contain pointer to variable to
565
 
 *                  receive local address.
566
 
 * @param remote    Optional argument which contain pointer to variable to
567
 
 *                  receive the remote address.
568
 
 * @param addrlen   On input, contains the length of the buffer for the
569
 
 *                  address, and on output, contains the actual length of the
570
 
 *                  address. This argument is optional.
571
 
 * @return
572
 
 *  - PJ_SUCCESS    When connection is available immediately, and the
573
 
 *                  parameters will be updated to contain information about
574
 
 *                  the new connection. In this case, a completion callback
575
 
 *                  WILL NOT be called.
576
 
 *  - PJ_EPENDING   If no connection is available immediately. When a new
577
 
 *                  connection arrives, the callback will be called.
578
 
 *  - non-zero      which indicates the appropriate error code.
579
 
 */
580
 
PJ_DECL(pj_status_t) pj_ioqueue_accept( pj_ioqueue_key_t *key,
581
 
                                        pj_ioqueue_op_key_t *op_key,
582
 
                                        pj_sock_t *new_sock,
583
 
                                        pj_sockaddr_t *local,
584
 
                                        pj_sockaddr_t *remote,
585
 
                                        int *addrlen );
586
 
 
587
 
/**
588
 
 * Initiate non-blocking socket connect. If the socket can NOT be connected
589
 
 * immediately, asynchronous connect() will be scheduled and caller will be
590
 
 * notified via completion callback when it calls pj_ioqueue_poll(). If
591
 
 * socket is connected immediately, the function returns PJ_SUCCESS and
592
 
 * completion callback WILL NOT be called.
593
 
 *
594
 
 * @param key       The key associated with TCP socket
595
 
 * @param addr      The remote address.
596
 
 * @param addrlen   The remote address length.
597
 
 *
598
 
 * @return
599
 
 *  - PJ_SUCCESS    If socket is connected immediately. In this case, the
600
 
 *                  completion callback WILL NOT be called.
601
 
 *  - PJ_EPENDING   If operation is queued, or
602
 
 *  - non-zero      Indicates the error code.
603
 
 */
604
 
PJ_DECL(pj_status_t) pj_ioqueue_connect( pj_ioqueue_key_t *key,
605
 
                                         const pj_sockaddr_t *addr,
606
 
                                         int addrlen );
607
 
 
608
 
#endif  /* PJ_HAS_TCP */
609
 
 
610
 
/**
611
 
 * Poll the I/O Queue for completed events.
612
 
 *
613
 
 * Note: polling the ioqueue is not necessary in Symbian. Please see
614
 
 * @ref PJ_SYMBIAN_OS for more info.
615
 
 *
616
 
 * @param ioque         the I/O Queue.
617
 
 * @param timeout       polling timeout, or NULL if the thread wishes to wait
618
 
 *                      indefinetely for the event.
619
 
 *
620
 
 * @return
621
 
 *  - zero if timed out (no event).
622
 
 *  - (<0) if error occured during polling. Callback will NOT be called.
623
 
 *  - (>1) to indicate numbers of events. Callbacks have been called.
624
 
 */
625
 
PJ_DECL(int) pj_ioqueue_poll( pj_ioqueue_t *ioque,
626
 
                              const pj_time_val *timeout);
627
 
 
628
 
 
629
 
/**
630
 
 * Instruct the I/O Queue to read from the specified handle. This function
631
 
 * returns immediately (i.e. non-blocking) regardless whether some data has
632
 
 * been transfered. If the operation can't complete immediately, caller will
633
 
 * be notified about the completion when it calls pj_ioqueue_poll(). If data
634
 
 * is immediately available, the function will return PJ_SUCCESS and the
635
 
 * callback WILL NOT be called.
636
 
 *
637
 
 * @param key       The key that uniquely identifies the handle.
638
 
 * @param op_key    An operation specific key to be associated with the
639
 
 *                  pending operation, so that application can keep track of
640
 
 *                  which operation has been completed when the callback is
641
 
 *                  called. Caller must make sure that this key remains
642
 
 *                  valid until the function completes.
643
 
 * @param buffer    The buffer to hold the read data. The caller MUST make sure
644
 
 *                  that this buffer remain valid until the framework completes
645
 
 *                  reading the handle.
646
 
 * @param length    On input, it specifies the size of the buffer. If data is
647
 
 *                  available to be read immediately, the function returns
648
 
 *                  PJ_SUCCESS and this argument will be filled with the
649
 
 *                  amount of data read. If the function is pending, caller
650
 
 *                  will be notified about the amount of data read in the
651
 
 *                  callback. This parameter can point to local variable in
652
 
 *                  caller's stack and doesn't have to remain valid for the
653
 
 *                  duration of pending operation.
654
 
 * @param flags     Recv flag. If flags has PJ_IOQUEUE_ALWAYS_ASYNC then
655
 
 *                  the function will never return PJ_SUCCESS.
656
 
 *
657
 
 * @return
658
 
 *  - PJ_SUCCESS    If immediate data has been received in the buffer. In this
659
 
 *                  case, the callback WILL NOT be called.
660
 
 *  - PJ_EPENDING   If the operation has been queued, and the callback will be
661
 
 *                  called when data has been received.
662
 
 *  - non-zero      The return value indicates the error code.
663
 
 */
664
 
PJ_DECL(pj_status_t) pj_ioqueue_recv( pj_ioqueue_key_t *key,
665
 
                                      pj_ioqueue_op_key_t *op_key,
666
 
                                      void *buffer,
667
 
                                      pj_ssize_t *length,
668
 
                                      pj_uint32_t flags );
669
 
 
670
 
/**
671
 
 * This function behaves similarly as #pj_ioqueue_recv(), except that it is
672
 
 * normally called for socket, and the remote address will also be returned
673
 
 * along with the data. Caller MUST make sure that both buffer and addr
674
 
 * remain valid until the framework completes reading the data.
675
 
 *
676
 
 * @param key       The key that uniquely identifies the handle.
677
 
 * @param op_key    An operation specific key to be associated with the
678
 
 *                  pending operation, so that application can keep track of
679
 
 *                  which operation has been completed when the callback is
680
 
 *                  called.
681
 
 * @param buffer    The buffer to hold the read data. The caller MUST make sure
682
 
 *                  that this buffer remain valid until the framework completes
683
 
 *                  reading the handle.
684
 
 * @param length    On input, it specifies the size of the buffer. If data is
685
 
 *                  available to be read immediately, the function returns
686
 
 *                  PJ_SUCCESS and this argument will be filled with the
687
 
 *                  amount of data read. If the function is pending, caller
688
 
 *                  will be notified about the amount of data read in the
689
 
 *                  callback. This parameter can point to local variable in
690
 
 *                  caller's stack and doesn't have to remain valid for the
691
 
 *                  duration of pending operation.
692
 
 * @param flags     Recv flag. If flags has PJ_IOQUEUE_ALWAYS_ASYNC then
693
 
 *                  the function will never return PJ_SUCCESS.
694
 
 * @param addr      Optional Pointer to buffer to receive the address.
695
 
 * @param addrlen   On input, specifies the length of the address buffer.
696
 
 *                  On output, it will be filled with the actual length of
697
 
 *                  the address. This argument can be NULL if \c addr is not
698
 
 *                  specified.
699
 
 *
700
 
 * @return
701
 
 *  - PJ_SUCCESS    If immediate data has been received. In this case, the
702
 
 *                  callback must have been called before this function
703
 
 *                  returns, and no pending operation is scheduled.
704
 
 *  - PJ_EPENDING   If the operation has been queued.
705
 
 *  - non-zero      The return value indicates the error code.
706
 
 */
707
 
PJ_DECL(pj_status_t) pj_ioqueue_recvfrom( pj_ioqueue_key_t *key,
708
 
                                          pj_ioqueue_op_key_t *op_key,
709
 
                                          void *buffer,
710
 
                                          pj_ssize_t *length,
711
 
                                          pj_uint32_t flags,
712
 
                                          pj_sockaddr_t *addr,
713
 
                                          int *addrlen);
714
 
 
715
 
/**
716
 
 * Instruct the I/O Queue to write to the handle. This function will return
717
 
 * immediately (i.e. non-blocking) regardless whether some data has been
718
 
 * transfered. If the function can't complete immediately, the caller will
719
 
 * be notified about the completion when it calls pj_ioqueue_poll(). If
720
 
 * operation completes immediately and data has been transfered, the function
721
 
 * returns PJ_SUCCESS and the callback will NOT be called.
722
 
 *
723
 
 * @param key       The key that identifies the handle.
724
 
 * @param op_key    An operation specific key to be associated with the
725
 
 *                  pending operation, so that application can keep track of
726
 
 *                  which operation has been completed when the callback is
727
 
 *                  called.
728
 
 * @param data      The data to send. Caller MUST make sure that this buffer
729
 
 *                  remains valid until the write operation completes.
730
 
 * @param length    On input, it specifies the length of data to send. When
731
 
 *                  data was sent immediately, this function returns PJ_SUCCESS
732
 
 *                  and this parameter contains the length of data sent. If
733
 
 *                  data can not be sent immediately, an asynchronous operation
734
 
 *                  is scheduled and caller will be notified via callback the
735
 
 *                  number of bytes sent. This parameter can point to local
736
 
 *                  variable on caller's stack and doesn't have to remain
737
 
 *                  valid until the operation has completed.
738
 
 * @param flags     Send flags. If flags has PJ_IOQUEUE_ALWAYS_ASYNC then
739
 
 *                  the function will never return PJ_SUCCESS.
740
 
 *
741
 
 * @return
742
 
 *  - PJ_SUCCESS    If data was immediately transfered. In this case, no
743
 
 *                  pending operation has been scheduled and the callback
744
 
 *                  WILL NOT be called.
745
 
 *  - PJ_EPENDING   If the operation has been queued. Once data base been
746
 
 *                  transfered, the callback will be called.
747
 
 *  - non-zero      The return value indicates the error code.
748
 
 */
749
 
PJ_DECL(pj_status_t) pj_ioqueue_send( pj_ioqueue_key_t *key,
750
 
                                      pj_ioqueue_op_key_t *op_key,
751
 
                                      const void *data,
752
 
                                      pj_ssize_t *length,
753
 
                                      pj_uint32_t flags );
754
 
 
755
 
 
756
 
/**
757
 
 * Instruct the I/O Queue to write to the handle. This function will return
758
 
 * immediately (i.e. non-blocking) regardless whether some data has been
759
 
 * transfered. If the function can't complete immediately, the caller will
760
 
 * be notified about the completion when it calls pj_ioqueue_poll(). If
761
 
 * operation completes immediately and data has been transfered, the function
762
 
 * returns PJ_SUCCESS and the callback will NOT be called.
763
 
 *
764
 
 * @param key       the key that identifies the handle.
765
 
 * @param op_key    An operation specific key to be associated with the
766
 
 *                  pending operation, so that application can keep track of
767
 
 *                  which operation has been completed when the callback is
768
 
 *                  called.
769
 
 * @param data      the data to send. Caller MUST make sure that this buffer
770
 
 *                  remains valid until the write operation completes.
771
 
 * @param length    On input, it specifies the length of data to send. When
772
 
 *                  data was sent immediately, this function returns PJ_SUCCESS
773
 
 *                  and this parameter contains the length of data sent. If
774
 
 *                  data can not be sent immediately, an asynchronous operation
775
 
 *                  is scheduled and caller will be notified via callback the
776
 
 *                  number of bytes sent. This parameter can point to local
777
 
 *                  variable on caller's stack and doesn't have to remain
778
 
 *                  valid until the operation has completed.
779
 
 * @param flags     send flags. If flags has PJ_IOQUEUE_ALWAYS_ASYNC then
780
 
 *                  the function will never return PJ_SUCCESS.
781
 
 * @param addr      Optional remote address.
782
 
 * @param addrlen   Remote address length, \c addr is specified.
783
 
 *
784
 
 * @return
785
 
 *  - PJ_SUCCESS    If data was immediately written.
786
 
 *  - PJ_EPENDING   If the operation has been queued.
787
 
 *  - non-zero      The return value indicates the error code.
788
 
 */
789
 
PJ_DECL(pj_status_t) pj_ioqueue_sendto( pj_ioqueue_key_t *key,
790
 
                                        pj_ioqueue_op_key_t *op_key,
791
 
                                        const void *data,
792
 
                                        pj_ssize_t *length,
793
 
                                        pj_uint32_t flags,
794
 
                                        const pj_sockaddr_t *addr,
795
 
                                        int addrlen);
796
 
 
797
 
 
798
 
/**
799
 
 * !}
800
 
 */
801
 
 
802
 
PJ_END_DECL
803
 
 
804
 
#endif  /* __PJ_IOQUEUE_H__ */