← Back to branch summary

~ubuntu-branches/ubuntu/trusty/sflphone/trusty

« back to all changes in this revision

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

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (4.3.4 sid)
  • Revision ID: package-import@ubuntu.com-20140128182336-jrsv0k9u6cawc068
Tags: 1.3.0-1
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/pool.h
1
 
/* $Id: pool.h 3553 2011-05-05 06:14:19Z nanang $ */
2
 
/*
3
 
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
 
 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5
 
 *
6
 
 * This program is free software; you can redistribute it and/or modify
7
 
 * it under the terms of the GNU General Public License as published by
8
 
 * the Free Software Foundation; either version 2 of the License, or
9
 
 * (at your option) any later version.
10
 
 *
11
 
 * This program is distributed in the hope that it will be useful,
12
 
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13
 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14
 
 * GNU General Public License for more details.
15
 
 *
16
 
 * You should have received a copy of the GNU General Public License
17
 
 * along with this program; if not, write to the Free Software
18
 
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
19
 
 */
20
 
 
21
 
#include <pj/list.h>
22
 
 
23
 
/* See if we use pool's alternate API.
24
 
 * The alternate API is used e.g. to implement pool debugging.
25
 
 */
26
 
#if PJ_HAS_POOL_ALT_API
27
 
#  include <pj/pool_alt.h>
28
 
#endif
29
 
 
30
 
 
31
 
#ifndef __PJ_POOL_H__
32
 
#define __PJ_POOL_H__
33
 
 
34
 
/**
35
 
 * @file pool.h
36
 
 * @brief Memory Pool.
37
 
 */
38
 
 
39
 
PJ_BEGIN_DECL
40
 
 
41
 
/**
42
 
 * @defgroup PJ_POOL_GROUP Fast Memory Pool
43
 
 * @brief
44
 
 * Memory pools allow dynamic memory allocation comparable to malloc or the
45
 
 * new in operator C++. Those implementations are not desirable for very
46
 
 * high performance applications or real-time systems, because of the
47
 
 * performance bottlenecks and it suffers from fragmentation issue.
48
 
 *
49
 
 * \section PJ_POOL_INTRO_SEC PJLIB's Memory Pool
50
 
 * \subsection PJ_POOL_ADVANTAGE_SUBSEC Advantages
51
 
 *
52
 
 * PJLIB's pool has many advantages over traditional malloc/new operator and
53
 
 * over other memory pool implementations, because:
54
 
 *  - unlike other memory pool implementation, it allows allocation of
55
 
 *    memory chunks of different sizes,
56
 
 *  - it's very very fast.
57
 
 *    \n
58
 
 *    Memory chunk allocation is not only an O(1)
59
 
 *    operation, but it's also very simple (just
60
 
 *    few pointer arithmetic operations) and it doesn't require locking
61
 
 *    any mutex,
62
 
 *  - it's memory efficient.
63
 
 *    \n
64
 
 *    Pool doesn't keep track individual memory chunks allocated by
65
 
 *    applications, so there is no additional overhead needed for each
66
 
 *    memory allocation (other than possible additional of few bytes, up to
67
 
 *    PJ_POOL_ALIGNMENT-1, for aligning the memory).
68
 
 *    But see the @ref PJ_POOL_CAVEATS_SUBSEC below.
69
 
 *  - it prevents memory leaks.
70
 
 *    \n
71
 
 *    Memory pool inherently has garbage collection functionality. In fact,
72
 
 *    there is no need to free the chunks allocated from the memory pool.
73
 
 *    All chunks previously allocated from the pool will be freed once the
74
 
 *    pool itself is destroyed. This would prevent memory leaks that haunt
75
 
 *    programmers for decades, and it provides additional performance
76
 
 *    advantage over traditional malloc/new operator.
77
 
 *
78
 
 * Even more, PJLIB's memory pool provides some additional usability and
79
 
 * flexibility for applications:
80
 
 *  - memory leaks are easily traceable, since memory pool is assigned name,
81
 
 *    and application can inspect what pools currently active in the system.
82
 
 *  - by design, memory allocation from a pool is not thread safe. We assumed
83
 
 *    that a pool will be owned by a higher level object, and thread safety
84
 
 *    should be handled by that object. This enables very fast pool operations
85
 
 *    and prevents unnecessary locking operations,
86
 
 *  - by default, the memory pool API behaves more like C++ new operator,
87
 
 *    in that it will throw PJ_NO_MEMORY_EXCEPTION exception (see
88
 
 *    @ref PJ_EXCEPT) when memory chunk allocation fails. This enables failure
89
 
 *    handling to be done on more high level function (instead of checking
90
 
 *    the result of pj_pool_alloc() everytime). If application doesn't like
91
 
 *    this, the default behavior can be changed on global basis by supplying
92
 
 *    different policy to the pool factory.
93
 
 *  - any memory allocation backend allocator/deallocator may be used. By
94
 
 *    default, the policy uses malloc() and free() to manage the pool's block,
95
 
 *    but application may use different strategy, for example to allocate
96
 
 *    memory blocks from a globally static memory location.
97
 
 *
98
 
 *
99
 
 * \subsection PJ_POOL_PERFORMANCE_SUBSEC Performance
100
 
 *
101
 
 * The result of PJLIB's memory design and careful implementation is a
102
 
 * memory allocation strategy that can speed-up the memory allocations
103
 
 * and deallocations by up to <b>30 times</b> compared to standard
104
 
 * malloc()/free() (more than 150 million allocations per second on a
105
 
 * P4/3.0GHz Linux machine).
106
 
 *
107
 
 * (Note: your mileage may vary, of course. You can see how much PJLIB's
108
 
 *  pool improves the performance over malloc()/free() in your target
109
 
 *  system by running pjlib-test application).
110
 
 *
111
 
 *
112
 
 * \subsection PJ_POOL_CAVEATS_SUBSEC Caveats
113
 
 *
114
 
 * There are some caveats though!
115
 
 *
116
 
 * When creating pool, PJLIB requires applications to specify the initial
117
 
 * pool size, and as soon as the pool is created, PJLIB allocates memory
118
 
 * from the system by that size. Application designers MUST choose the
119
 
 * initial pool size carefully, since choosing too big value will result in
120
 
 * wasting system's memory.
121
 
 *
122
 
 * But the pool can grow. Application designer can specify how the
123
 
 * pool will grow in size, by specifying the size increment when creating
124
 
 * the pool.
125
 
 *
126
 
 * The pool, however, <b>cannot</b> shrink! Since there is <b>no</b>
127
 
 * function to deallocate memory chunks, there is no way for the pool to
128
 
 * release back unused memory to the system.
129
 
 * Application designers must be aware that constant memory allocations
130
 
 * from pool that has infinite life-time may cause the memory usage of
131
 
 * the application to grow over time.
132
 
 *
133
 
 *
134
 
 * \section PJ_POOL_USING_SEC Using Memory Pool
135
 
 *
136
 
 * This section describes how to use PJLIB's memory pool framework.
137
 
 * As we hope the readers will witness, PJLIB's memory pool API is quite
138
 
 * straightforward.
139
 
 *
140
 
 * \subsection PJ_POOL_USING_F Create Pool Factory
141
 
 * First, application needs to initialize a pool factory (this normally
142
 
 * only needs to be done once in one application). PJLIB provides
143
 
 * a pool factory implementation called caching pool (see @ref
144
 
 * PJ_CACHING_POOL), and it is initialized by calling #pj_caching_pool_init().
145
 
 *
146
 
 * \subsection PJ_POOL_USING_P Create The Pool
147
 
 * Then application creates the pool object itself with #pj_pool_create(),
148
 
 * specifying among other thing the pool factory where the pool should
149
 
 * be created from, the pool name, initial size, and increment/expansion
150
 
 * size.
151
 
 *
152
 
 * \subsection PJ_POOL_USING_M Allocate Memory as Required
153
 
 * Then whenever application needs to allocate dynamic memory, it would
154
 
 * call #pj_pool_alloc(), #pj_pool_calloc(), or #pj_pool_zalloc() to
155
 
 * allocate memory chunks from the pool.
156
 
 *
157
 
 * \subsection PJ_POOL_USING_DP Destroy the Pool
158
 
 * When application has finished with the pool, it should call
159
 
 * #pj_pool_release() to release the pool object back to the factory.
160
 
 * Depending on the types of the factory, this may release the memory back
161
 
 * to the operating system.
162
 
 *
163
 
 * \subsection PJ_POOL_USING_Dc Destroy the Pool Factory
164
 
 * And finally, before application quites, it should deinitialize the
165
 
 * pool factory, to make sure that all memory blocks allocated by the
166
 
 * factory are released back to the operating system. After this, of
167
 
 * course no more memory pool allocation can be requested.
168
 
 *
169
 
 * \subsection PJ_POOL_USING_EX Example
170
 
 * Below is a sample complete program that utilizes PJLIB's memory pool.
171
 
 *
172
 
 * \code
173
 
 
174
 
   #include <pjlib.h>
175
 
 
176
 
   #define THIS_FILE    "pool_sample.c"
177
 
 
178
 
   static void my_perror(const char *title, pj_status_t status)
179
 
   {
180
 
        char errmsg[PJ_ERR_MSG_SIZE];
181
 
 
182
 
        pj_strerror(status, errmsg, sizeof(errmsg));
183
 
        PJ_LOG(1,(THIS_FILE, "%s: %s [status=%d]", title, errmsg, status));
184
 
   }
185
 
 
186
 
   static void pool_demo_1(pj_pool_factory *pfactory)
187
 
   {
188
 
        unsigned i;
189
 
        pj_pool_t *pool;
190
 
 
191
 
        // Must create pool before we can allocate anything
192
 
        pool = pj_pool_create(pfactory,  // the factory
193
 
                              "pool1",   // pool's name
194
 
                              4000,      // initial size
195
 
                              4000,      // increment size
196
 
                              NULL);     // use default callback.
197
 
        if (pool == NULL) {
198
 
            my_perror("Error creating pool", PJ_ENOMEM);
199
 
            return;
200
 
        }
201
 
 
202
 
        // Demo: allocate some memory chunks
203
 
        for (i=0; i<1000; ++i) {
204
 
            void *p;
205
 
 
206
 
            p = pj_pool_alloc(pool, (pj_rand()+1) % 512);
207
 
 
208
 
            // Do something with p
209
 
            ...
210
 
 
211
 
            // Look! No need to free p!!
212
 
        }
213
 
 
214
 
        // Done with silly demo, must free pool to release all memory.
215
 
        pj_pool_release(pool);
216
 
   }
217
 
 
218
 
   int main()
219
 
   {
220
 
        pj_caching_pool cp;
221
 
        pj_status_t status;
222
 
 
223
 
        // Must init PJLIB before anything else
224
 
        status = pj_init();
225
 
        if (status != PJ_SUCCESS) {
226
 
            my_perror("Error initializing PJLIB", status);
227
 
            return 1;
228
 
        }
229
 
 
230
 
        // Create the pool factory, in this case, a caching pool,
231
 
        // using default pool policy.
232
 
        pj_caching_pool_init(&cp, NULL, 1024*1024 );
233
 
 
234
 
        // Do a demo
235
 
        pool_demo_1(&cp.factory);
236
 
 
237
 
        // Done with demos, destroy caching pool before exiting app.
238
 
        pj_caching_pool_destroy(&cp);
239
 
 
240
 
        return 0;
241
 
   }
242
 
 
243
 
   \endcode
244
 
 *
245
 
 * More information about pool factory, the pool object, and caching pool
246
 
 * can be found on the Module Links below.
247
 
 */
248
 
 
249
 
 
250
 
/**
251
 
 * @defgroup PJ_POOL Memory Pool Object
252
 
 * @ingroup PJ_POOL_GROUP
253
 
 * @brief
254
 
 * The memory pool is an opaque object created by pool factory.
255
 
 * Application uses this object to request a memory chunk, by calling
256
 
 * #pj_pool_alloc(), #pj_pool_calloc(), or #pj_pool_zalloc().
257
 
 * When the application has finished using
258
 
 * the pool, it must call #pj_pool_release() to free all the chunks previously
259
 
 * allocated and release the pool back to the factory.
260
 
 *
261
 
 * A memory pool is initialized with an initial amount of memory, which is
262
 
 * called a block. Pool can be configured to dynamically allocate more memory
263
 
 * blocks when it runs out of memory.
264
 
 *
265
 
 * The pool doesn't keep track of individual memory allocations
266
 
 * by user, and the user doesn't have to free these indidual allocations. This
267
 
 * makes memory allocation simple and very fast. All the memory allocated from
268
 
 * the pool will be destroyed when the pool itself is destroyed.
269
 
 *
270
 
 * \section PJ_POOL_THREADING_SEC More on Threading Policies
271
 
 * - By design, memory allocation from a pool is not thread safe. We assumed
272
 
 *   that a pool will be owned by an object, and thread safety should be
273
 
 *   handled by that object. Thus these functions are not thread safe:
274
 
 *      - #pj_pool_alloc,
275
 
 *      - #pj_pool_calloc,
276
 
 *      - and other pool statistic functions.
277
 
 * - Threading in the pool factory is decided by the policy set for the
278
 
 *   factory when it was created.
279
 
 *
280
 
 * \section PJ_POOL_EXAMPLES_SEC Examples
281
 
 *
282
 
 * For some sample codes on how to use the pool, please see:
283
 
 *  - @ref page_pjlib_pool_test
284
 
 *
285
 
 * @{
286
 
 */
287
 
 
288
 
/**
289
 
 * The type for function to receive callback from the pool when it is unable
290
 
 * to allocate memory. The elegant way to handle this condition is to throw
291
 
 * exception, and this is what is expected by most of this library
292
 
 * components.
293
 
 */
294
 
typedef void pj_pool_callback(pj_pool_t *pool, pj_size_t size);
295
 
 
296
 
/**
297
 
 * This class, which is used internally by the pool, describes a single
298
 
 * block of memory from which user memory allocations will be allocated from.
299
 
 */
300
 
typedef struct pj_pool_block
301
 
{
302
 
    PJ_DECL_LIST_MEMBER(struct pj_pool_block);  /**< List's prev and next.  */
303
 
    unsigned char    *buf;                      /**< Start of buffer.       */
304
 
    unsigned char    *cur;                      /**< Current alloc ptr.     */
305
 
    unsigned char    *end;                      /**< End of buffer.         */
306
 
} pj_pool_block;
307
 
 
308
 
 
309
 
/**
310
 
 * This structure describes the memory pool. Only implementors of pool factory
311
 
 * need to care about the contents of this structure.
312
 
 */
313
 
struct pj_pool_t
314
 
{
315
 
    PJ_DECL_LIST_MEMBER(struct pj_pool_t);  /**< Standard list elements.    */
316
 
 
317
 
    /** Pool name */
318
 
    char            obj_name[PJ_MAX_OBJ_NAME];
319
 
 
320
 
    /** Pool factory. */
321
 
    pj_pool_factory *factory;
322
 
 
323
 
    /** Data put by factory */
324
 
    void            *factory_data;
325
 
 
326
 
    /** Current capacity allocated by the pool. */
327
 
    pj_size_t       capacity;
328
 
 
329
 
    /** Size of memory block to be allocated when the pool runs out of memory */
330
 
    pj_size_t       increment_size;
331
 
 
332
 
    /** List of memory blocks allcoated by the pool. */
333
 
    pj_pool_block   block_list;
334
 
 
335
 
    /** The callback to be called when the pool is unable to allocate memory. */
336
 
    pj_pool_callback *callback;
337
 
 
338
 
};
339
 
 
340
 
 
341
 
/**
342
 
 * Guidance on how much memory required for initial pool administrative data.
343
 
 */
344
 
#define PJ_POOL_SIZE            (sizeof(struct pj_pool_t))
345
 
 
346
 
/**
347
 
 * Pool memory alignment (must be power of 2).
348
 
 */
349
 
#ifndef PJ_POOL_ALIGNMENT
350
 
#   define PJ_POOL_ALIGNMENT    4
351
 
#endif
352
 
 
353
 
/**
354
 
 * Create a new pool from the pool factory. This wrapper will call create_pool
355
 
 * member of the pool factory.
356
 
 *
357
 
 * @param factory           The pool factory.
358
 
 * @param name              The name to be assigned to the pool. The name should
359
 
 *                          not be longer than PJ_MAX_OBJ_NAME (32 chars), or
360
 
 *                          otherwise it will be truncated.
361
 
 * @param initial_size      The size of initial memory blocks taken by the pool.
362
 
 *                          Note that the pool will take 68+20 bytes for
363
 
 *                          administrative area from this block.
364
 
 * @param increment_size    the size of each additional blocks to be allocated
365
 
 *                          when the pool is running out of memory. If user
366
 
 *                          requests memory which is larger than this size, then
367
 
 *                          an error occurs.
368
 
 *                          Note that each time a pool allocates additional block,
369
 
 *                          it needs PJ_POOL_SIZE more to store some
370
 
 *                          administrative info.
371
 
 * @param callback          Callback to be called when error occurs in the pool.
372
 
 *                          If this value is NULL, then the callback from pool
373
 
 *                          factory policy will be used.
374
 
 *                          Note that when an error occurs during pool creation,
375
 
 *                          the callback itself is not called. Instead, NULL
376
 
 *                          will be returned.
377
 
 *
378
 
 * @return                  The memory pool, or NULL.
379
 
 */
380
 
PJ_IDECL(pj_pool_t*) pj_pool_create(pj_pool_factory *factory,
381
 
                                    const char *name,
382
 
                                    pj_size_t initial_size,
383
 
                                    pj_size_t increment_size,
384
 
                                    pj_pool_callback *callback);
385
 
 
386
 
/**
387
 
 * Release the pool back to pool factory.
388
 
 *
389
 
 * @param pool      Memory pool.
390
 
 */
391
 
PJ_IDECL(void) pj_pool_release( pj_pool_t *pool );
392
 
 
393
 
/**
394
 
 * Get pool object name.
395
 
 *
396
 
 * @param pool the pool.
397
 
 *
398
 
 * @return pool name as NULL terminated string.
399
 
 */
400
 
PJ_IDECL(const char *) pj_pool_getobjname( const pj_pool_t *pool );
401
 
 
402
 
/**
403
 
 * Reset the pool to its state when it was initialized.
404
 
 * This means that if additional blocks have been allocated during runtime,
405
 
 * then they will be freed. Only the original block allocated during
406
 
 * initialization is retained. This function will also reset the internal
407
 
 * counters, such as pool capacity and used size.
408
 
 *
409
 
 * @param pool the pool.
410
 
 */
411
 
PJ_DECL(void) pj_pool_reset( pj_pool_t *pool );
412
 
 
413
 
 
414
 
/**
415
 
 * Get the pool capacity, that is, the system storage that have been allocated
416
 
 * by the pool, and have been used/will be used to allocate user requests.
417
 
 * There's no guarantee that the returned value represent a single
418
 
 * contiguous block, because the capacity may be spread in several blocks.
419
 
 *
420
 
 * @param pool  the pool.
421
 
 *
422
 
 * @return the capacity.
423
 
 */
424
 
PJ_IDECL(pj_size_t) pj_pool_get_capacity( pj_pool_t *pool );
425
 
 
426
 
/**
427
 
 * Get the total size of user allocation request.
428
 
 *
429
 
 * @param pool  the pool.
430
 
 *
431
 
 * @return the total size.
432
 
 */
433
 
PJ_IDECL(pj_size_t) pj_pool_get_used_size( pj_pool_t *pool );
434
 
 
435
 
/**
436
 
 * Allocate storage with the specified size from the pool.
437
 
 * If there's no storage available in the pool, then the pool can allocate more
438
 
 * blocks if the increment size is larger than the requested size.
439
 
 *
440
 
 * @param pool      the pool.
441
 
 * @param size      the requested size.
442
 
 *
443
 
 * @return pointer to the allocated memory.
444
 
 *
445
 
 * @see PJ_POOL_ALLOC_T
446
 
 */
447
 
PJ_IDECL(void*) pj_pool_alloc( pj_pool_t *pool, pj_size_t size);
448
 
 
449
 
/**
450
 
 * Allocate storage  from the pool, and initialize it to zero.
451
 
 * This function behaves like pj_pool_alloc(), except that the storage will
452
 
 * be initialized to zero.
453
 
 *
454
 
 * @param pool      the pool.
455
 
 * @param count     the number of elements in the array.
456
 
 * @param elem      the size of individual element.
457
 
 *
458
 
 * @return pointer to the allocated memory.
459
 
 */
460
 
PJ_IDECL(void*) pj_pool_calloc( pj_pool_t *pool, pj_size_t count,
461
 
                                pj_size_t elem);
462
 
 
463
 
 
464
 
/**
465
 
 * Allocate storage from the pool and initialize it to zero.
466
 
 *
467
 
 * @param pool      The pool.
468
 
 * @param size      The size to be allocated.
469
 
 *
470
 
 * @return          Pointer to the allocated memory.
471
 
 *
472
 
 * @see PJ_POOL_ZALLOC_T
473
 
 */
474
 
PJ_INLINE(void*) pj_pool_zalloc(pj_pool_t *pool, pj_size_t size)
475
 
{
476
 
    return pj_pool_calloc(pool, 1, size);
477
 
}
478
 
 
479
 
 
480
 
/**
481
 
 * This macro allocates memory from the pool and returns the instance of
482
 
 * the specified type. It provides a stricker type safety than pj_pool_alloc()
483
 
 * since the return value of this macro will be type-casted to the specified
484
 
 * type.
485
 
 *
486
 
 * @param pool      The pool
487
 
 * @param type      The type of object to be allocated
488
 
 *
489
 
 * @return          Memory buffer of the specified type.
490
 
 */
491
 
#define PJ_POOL_ALLOC_T(pool,type) \
492
 
            ((type*)pj_pool_alloc(pool, sizeof(type)))
493
 
 
494
 
/**
495
 
 * This macro allocates memory from the pool, zeroes the buffer, and
496
 
 * returns the instance of the specified type. It provides a stricker type
497
 
 * safety than pj_pool_zalloc() since the return value of this macro will be
498
 
 * type-casted to the specified type.
499
 
 *
500
 
 * @param pool      The pool
501
 
 * @param type      The type of object to be allocated
502
 
 *
503
 
 * @return          Memory buffer of the specified type.
504
 
 */
505
 
#define PJ_POOL_ZALLOC_T(pool,type) \
506
 
            ((type*)pj_pool_zalloc(pool, sizeof(type)))
507
 
 
508
 
/*
509
 
 * Internal functions
510
 
 */
511
 
PJ_IDECL(void*) pj_pool_alloc_from_block(pj_pool_block *block, pj_size_t size);
512
 
PJ_DECL(void*) pj_pool_allocate_find(pj_pool_t *pool, unsigned size);
513
 
 
514
 
 
515
 
 
516
 
/**
517
 
 * @}   // PJ_POOL
518
 
 */
519
 
 
520
 
/* **************************************************************************/
521
 
/**
522
 
 * @defgroup PJ_POOL_FACTORY Pool Factory and Policy
523
 
 * @ingroup PJ_POOL_GROUP
524
 
 * @brief
525
 
 * A pool object must be created through a factory. A factory not only provides
526
 
 * generic interface functions to create and release pool, but also provides
527
 
 * strategy to manage the life time of pools. One sample implementation,
528
 
 * \a pj_caching_pool, can be set to keep the pools released by application for
529
 
 * future use as long as the total memory is below the limit.
530
 
 *
531
 
 * The pool factory interface declared in PJLIB is designed to be extensible.
532
 
 * Application can define its own strategy by creating it's own pool factory
533
 
 * implementation, and this strategy can be used even by existing library
534
 
 * without recompilation.
535
 
 *
536
 
 * \section PJ_POOL_FACTORY_ITF Pool Factory Interface
537
 
 * The pool factory defines the following interface:
538
 
 *  - \a policy: the memory pool factory policy.
539
 
 *  - \a create_pool(): create a new memory pool.
540
 
 *  - \a release_pool(): release memory pool back to factory.
541
 
 *
542
 
 * \section PJ_POOL_FACTORY_POL Pool Factory Policy.
543
 
 *
544
 
 * A pool factory only defines functions to create and release pool and how
545
 
 * to manage pools, but the rest of the functionalities are controlled by
546
 
 * policy. A pool policy defines:
547
 
 *  - how memory block is allocated and deallocated (the default implementation
548
 
 *    allocates and deallocate memory by calling malloc() and free()).
549
 
 *  - callback to be called when memory allocation inside a pool fails (the
550
 
 *    default implementation will throw PJ_NO_MEMORY_EXCEPTION exception).
551
 
 *  - concurrency when creating and releasing pool from/to the factory.
552
 
 *
553
 
 * A pool factory can be given different policy during creation to make
554
 
 * it behave differently. For example, caching pool factory can be configured
555
 
 * to allocate and deallocate from a static/contiguous/preallocated memory
556
 
 * instead of using malloc()/free().
557
 
 *
558
 
 * What strategy/factory and what policy to use is not defined by PJLIB, but
559
 
 * instead is left to application to make use whichever is most efficient for
560
 
 * itself.
561
 
 *
562
 
 * The pool factory policy controls the behaviour of memory factories, and
563
 
 * defines the following interface:
564
 
 *  - \a block_alloc(): allocate memory block from backend memory mgmt/system.
565
 
 *  - \a block_free(): free memory block back to backend memory mgmt/system.
566
 
 * @{
567
 
 */
568
 
 
569
 
/* We unfortunately don't have support for factory policy options as now,
570
 
   so we keep this commented at the moment.
571
 
enum PJ_POOL_FACTORY_OPTION
572
 
{
573
 
    PJ_POOL_FACTORY_SERIALIZE = 1
574
 
};
575
 
*/
576
 
 
577
 
/**
578
 
 * This structure declares pool factory interface.
579
 
 */
580
 
typedef struct pj_pool_factory_policy
581
 
{
582
 
    /**
583
 
     * Allocate memory block (for use by pool). This function is called
584
 
     * by memory pool to allocate memory block.
585
 
     *
586
 
     * @param factory   Pool factory.
587
 
     * @param size      The size of memory block to allocate.
588
 
     *
589
 
     * @return          Memory block.
590
 
     */
591
 
    void* (*block_alloc)(pj_pool_factory *factory, pj_size_t size);
592
 
 
593
 
    /**
594
 
     * Free memory block.
595
 
     *
596
 
     * @param factory   Pool factory.
597
 
     * @param mem       Memory block previously allocated by block_alloc().
598
 
     * @param size      The size of memory block.
599
 
     */
600
 
    void (*block_free)(pj_pool_factory *factory, void *mem, pj_size_t size);
601
 
 
602
 
    /**
603
 
     * Default callback to be called when memory allocation fails.
604
 
     */
605
 
    pj_pool_callback *callback;
606
 
 
607
 
    /**
608
 
     * Option flags.
609
 
     */
610
 
    unsigned flags;
611
 
 
612
 
} pj_pool_factory_policy;
613
 
 
614
 
/**
615
 
 * \def PJ_NO_MEMORY_EXCEPTION
616
 
 * This constant denotes the exception number that will be thrown by default
617
 
 * memory factory policy when memory allocation fails.
618
 
 *
619
 
 * @see pj_NO_MEMORY_EXCEPTION()
620
 
 */
621
 
PJ_DECL_DATA(int) PJ_NO_MEMORY_EXCEPTION;
622
 
 
623
 
/**
624
 
 * Get #PJ_NO_MEMORY_EXCEPTION constant.
625
 
 */
626
 
PJ_DECL(int) pj_NO_MEMORY_EXCEPTION(void);
627
 
 
628
 
/**
629
 
 * This global variable points to default memory pool factory policy.
630
 
 * The behaviour of the default policy is:
631
 
 *  - block allocation and deallocation use malloc() and free().
632
 
 *  - callback will raise PJ_NO_MEMORY_EXCEPTION exception.
633
 
 *  - access to pool factory is not serialized (i.e. not thread safe).
634
 
 *
635
 
 * @see pj_pool_factory_get_default_policy
636
 
 */
637
 
PJ_DECL_DATA(pj_pool_factory_policy) pj_pool_factory_default_policy;
638
 
 
639
 
 
640
 
/**
641
 
 * Get the default pool factory policy.
642
 
 *
643
 
 * @return the pool policy.
644
 
 */
645
 
PJ_DECL(const pj_pool_factory_policy*) pj_pool_factory_get_default_policy(void);
646
 
 
647
 
 
648
 
/**
649
 
 * This structure contains the declaration for pool factory interface.
650
 
 */
651
 
struct pj_pool_factory
652
 
{
653
 
    /**
654
 
     * Memory pool policy.
655
 
     */
656
 
    pj_pool_factory_policy policy;
657
 
 
658
 
    /**
659
 
    * Create a new pool from the pool factory.
660
 
    *
661
 
    * @param factory    The pool factory.
662
 
    * @param name       the name to be assigned to the pool. The name should
663
 
    *                   not be longer than PJ_MAX_OBJ_NAME (32 chars), or
664
 
    *                   otherwise it will be truncated.
665
 
    * @param initial_size the size of initial memory blocks taken by the pool.
666
 
    *                   Note that the pool will take 68+20 bytes for
667
 
    *                   administrative area from this block.
668
 
    * @param increment_size the size of each additional blocks to be allocated
669
 
    *                   when the pool is running out of memory. If user
670
 
    *                   requests memory which is larger than this size, then
671
 
    *                   an error occurs.
672
 
    *                   Note that each time a pool allocates additional block,
673
 
    *                   it needs 20 bytes (equal to sizeof(pj_pool_block)) to
674
 
    *                   store some administrative info.
675
 
    * @param callback   Cllback to be called when error occurs in the pool.
676
 
    *                   Note that when an error occurs during pool creation,
677
 
    *                   the callback itself is not called. Instead, NULL
678
 
    *                   will be returned.
679
 
    *
680
 
    * @return the memory pool, or NULL.
681
 
    */
682
 
    pj_pool_t*  (*create_pool)( pj_pool_factory *factory,
683
 
                                const char *name,
684
 
                                pj_size_t initial_size,
685
 
                                pj_size_t increment_size,
686
 
                                pj_pool_callback *callback);
687
 
 
688
 
    /**
689
 
     * Release the pool to the pool factory.
690
 
     *
691
 
     * @param factory   The pool factory.
692
 
     * @param pool      The pool to be released.
693
 
    */
694
 
    void (*release_pool)( pj_pool_factory *factory, pj_pool_t *pool );
695
 
 
696
 
    /**
697
 
     * Dump pool status to log.
698
 
     *
699
 
     * @param factory   The pool factory.
700
 
     */
701
 
    void (*dump_status)( pj_pool_factory *factory, pj_bool_t detail );
702
 
 
703
 
    /**
704
 
     * This is optional callback to be called by allocation policy when
705
 
     * it allocates a new memory block. The factory may use this callback
706
 
     * for example to keep track of the total number of memory blocks
707
 
     * currently allocated by applications.
708
 
     *
709
 
     * @param factory       The pool factory.
710
 
     * @param size          Size requested by application.
711
 
     *
712
 
     * @return              MUST return PJ_TRUE, otherwise the block
713
 
     *                      allocation is cancelled.
714
 
     */
715
 
    pj_bool_t (*on_block_alloc)(pj_pool_factory *factory, pj_size_t size);
716
 
 
717
 
    /**
718
 
     * This is optional callback to be called by allocation policy when
719
 
     * it frees memory block. The factory may use this callback
720
 
     * for example to keep track of the total number of memory blocks
721
 
     * currently allocated by applications.
722
 
     *
723
 
     * @param factory       The pool factory.
724
 
     * @param size          Size freed.
725
 
     */
726
 
    void (*on_block_free)(pj_pool_factory *factory, pj_size_t size);
727
 
 
728
 
};
729
 
 
730
 
/**
731
 
 * This function is intended to be used by pool factory implementors.
732
 
 * @param factory           Pool factory.
733
 
 * @param name              Pool name.
734
 
 * @param initial_size      Initial size.
735
 
 * @param increment_size    Increment size.
736
 
 * @param callback          Callback.
737
 
 * @return                  The pool object, or NULL.
738
 
 */
739
 
PJ_DECL(pj_pool_t*) pj_pool_create_int( pj_pool_factory *factory,
740
 
                                        const char *name,
741
 
                                        pj_size_t initial_size,
742
 
                                        pj_size_t increment_size,
743
 
                                        pj_pool_callback *callback);
744
 
 
745
 
/**
746
 
 * This function is intended to be used by pool factory implementors.
747
 
 * @param pool              The pool.
748
 
 * @param name              Pool name.
749
 
 * @param increment_size    Increment size.
750
 
 * @param callback          Callback function.
751
 
 */
752
 
PJ_DECL(void) pj_pool_init_int( pj_pool_t *pool,
753
 
                                const char *name,
754
 
                                pj_size_t increment_size,
755
 
                                pj_pool_callback *callback);
756
 
 
757
 
/**
758
 
 * This function is intended to be used by pool factory implementors.
759
 
 * @param pool      The memory pool.
760
 
 */
761
 
PJ_DECL(void) pj_pool_destroy_int( pj_pool_t *pool );
762
 
 
763
 
 
764
 
/**
765
 
 * Dump pool factory state.
766
 
 * @param pf        The pool factory.
767
 
 * @param detail    Detail state required.
768
 
 */
769
 
PJ_INLINE(void) pj_pool_factory_dump( pj_pool_factory *pf,
770
 
                                      pj_bool_t detail )
771
 
{
772
 
    (*pf->dump_status)(pf, detail);
773
 
}
774
 
 
775
 
/**
776
 
 *  @}  // PJ_POOL_FACTORY
777
 
 */
778
 
 
779
 
/* **************************************************************************/
780
 
 
781
 
/**
782
 
 * @defgroup PJ_CACHING_POOL Caching Pool Factory
783
 
 * @ingroup PJ_POOL_GROUP
784
 
 * @brief
785
 
 * Caching pool is one sample implementation of pool factory where the
786
 
 * factory can reuse memory to create a pool. Application defines what the
787
 
 * maximum memory the factory can hold, and when a pool is released the
788
 
 * factory decides whether to destroy the pool or to keep it for future use.
789
 
 * If the total amount of memory in the internal cache is still within the
790
 
 * limit, the factory will keep the pool in the internal cache, otherwise the
791
 
 * pool will be destroyed, thus releasing the memory back to the system.
792
 
 *
793
 
 * @{
794
 
 */
795
 
 
796
 
/**
797
 
 * Number of unique sizes, to be used as index to the free list.
798
 
 * Each pool in the free list is organized by it's size.
799
 
 */
800
 
#define PJ_CACHING_POOL_ARRAY_SIZE      16
801
 
 
802
 
/**
803
 
 * Declaration for caching pool. Application doesn't normally need to
804
 
 * care about the contents of this struct, it is only provided here because
805
 
 * application need to define an instance of this struct (we can not allocate
806
 
 * the struct from a pool since there is no pool factory yet!).
807
 
 */
808
 
struct pj_caching_pool
809
 
{
810
 
    /** Pool factory interface, must be declared first. */
811
 
    pj_pool_factory factory;
812
 
 
813
 
    /** Current factory's capacity, i.e. number of bytes that are allocated
814
 
     *  and available for application in this factory. The factory's
815
 
     *  capacity represents the size of all pools kept by this factory
816
 
     *  in it's free list, which will be returned to application when it
817
 
     *  requests to create a new pool.
818
 
     */
819
 
    pj_size_t       capacity;
820
 
 
821
 
    /** Maximum size that can be held by this factory. Once the capacity
822
 
     *  has exceeded @a max_capacity, further #pj_pool_release() will
823
 
     *  flush the pool. If the capacity is still below the @a max_capacity,
824
 
     *  #pj_pool_release() will save the pool to the factory's free list.
825
 
     */
826
 
    pj_size_t       max_capacity;
827
 
 
828
 
    /**
829
 
     * Number of pools currently held by applications. This number gets
830
 
     * incremented everytime #pj_pool_create() is called, and gets
831
 
     * decremented when #pj_pool_release() is called.
832
 
     */
833
 
    pj_size_t       used_count;
834
 
 
835
 
    /**
836
 
     * Total size of memory currently used by application.
837
 
     */
838
 
    pj_size_t       used_size;
839
 
 
840
 
    /**
841
 
     * The maximum size of memory used by application throughout the life
842
 
     * of the caching pool.
843
 
     */
844
 
    pj_size_t       peak_used_size;
845
 
 
846
 
    /**
847
 
     * Lists of pools in the cache, indexed by pool size.
848
 
     */
849
 
    pj_list         free_list[PJ_CACHING_POOL_ARRAY_SIZE];
850
 
 
851
 
    /**
852
 
     * List of pools currently allocated by applications.
853
 
     */
854
 
    pj_list         used_list;
855
 
 
856
 
    /**
857
 
     * Internal pool.
858
 
     */
859
 
    char            pool_buf[256 * (sizeof(long) / 4)];
860
 
 
861
 
    /**
862
 
     * Mutex.
863
 
     */
864
 
    pj_lock_t      *lock;
865
 
};
866
 
 
867
 
 
868
 
 
869
 
/**
870
 
 * Initialize caching pool.
871
 
 *
872
 
 * @param ch_pool       The caching pool factory to be initialized.
873
 
 * @param policy        Pool factory policy.
874
 
 * @param max_capacity  The total capacity to be retained in the cache. When
875
 
 *                      the pool is returned to the cache, it will be kept in
876
 
 *                      recycling list if the total capacity of pools in this
877
 
 *                      list plus the capacity of the pool is still below this
878
 
 *                      value.
879
 
 */
880
 
PJ_DECL(void) pj_caching_pool_init( pj_caching_pool *ch_pool,
881
 
                                    const pj_pool_factory_policy *policy,
882
 
                                    pj_size_t max_capacity);
883
 
 
884
 
 
885
 
/**
886
 
 * Destroy caching pool, and release all the pools in the recycling list.
887
 
 *
888
 
 * @param ch_pool       The caching pool.
889
 
 */
890
 
PJ_DECL(void) pj_caching_pool_destroy( pj_caching_pool *ch_pool );
891
 
 
892
 
/**
893
 
 * @}   // PJ_CACHING_POOL
894
 
 */
895
 
 
896
 
#  if PJ_FUNCTIONS_ARE_INLINED
897
 
#    include "pool_i.h"
898
 
#  endif
899
 
 
900
 
PJ_END_DECL
901
 
 
902
 
#endif  /* __PJ_POOL_H__ */