Changeset 691


Ignore:
Timestamp:
Aug 25, 2006 12:41:05 PM (16 years ago)
Author:
bennylp
Message:

Yet another documentation/doxygen update

Location:
pjproject/trunk
Files:
6 edited

Legend:

Unmodified
Added
Removed
  • pjproject/trunk/pjlib/docs/doxygen.cfg

    r690 r691  
    1818# by quotes) that should identify the project. 
    1919 
    20 PROJECT_NAME           =  "PJLIB Open Source" 
     20PROJECT_NAME           =  "PJLIB Reference" 
    2121 
    2222# The PROJECT_NUMBER tag can be used to enter a project or revision number.  
  • pjproject/trunk/pjlib/docs/footer.html

    r690 r691  
    22<hr><center> 
    33PJLIB Open Source, high performance, small footprint, and very very portable framework<br> 
    4 (C)2003-2006 Benny Prijono 
     4(C)2001-2006 Benny Prijono 
    55</center> 
    66 
  • pjproject/trunk/pjlib/include/pj/doxygen.h

    r690 r691  
    394394 * Enjoy using PJLIB! 
    395395 * 
    396  * Benny Prijono < bennylp at pjproject dot net > 
     396 * Benny Prijono < bennylp at pjsip dot org > 
    397397 */ 
    398398 
  • pjproject/trunk/pjlib/include/pj/ioqueue.h

    r622 r691  
    6060 
    6161/** 
    62  * @defgroup PJ_IOQUEUE I/O Event Dispatching Queue 
     62 * @defgroup PJ_IOQUEUE IOQueue: I/O Event Dispatching with Proactor Pattern 
    6363 * @ingroup PJ_IO 
    6464 * @{ 
  • pjproject/trunk/pjlib/include/pj/pool.h

    r622 r691  
    3939 
    4040/** 
    41  * @defgroup PJ_POOL_GROUP Memory Pool Management 
     41 * @defgroup PJ_POOL_GROUP Fast Memory Pool 
    4242 * @ingroup PJ 
    4343 * @brief 
    44  * Memory pool management provides API to allocate and deallocate memory from 
    45  * memory pool and to manage and establish policy for pool creation and 
    46  * destruction in pool factory. 
    47  * 
    48  * \section PJ_POOL_FACTORY_SEC Pool Factory 
    49  * See: \ref PJ_POOL_FACTORY "Pool Factory" 
    50  * 
    51  * A memory pool must be created through a factory. A factory not only provides 
    52  * generic interface functions to create and release pool, but also provides  
    53  * strategy to manage the life time of pools. One sample implementation,  
    54  * \a pj_caching_pool, can be set to keep the pools released by application for 
    55  * future use as long as the total memory is below the limit. 
     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 
    5651 *  
    57  * The pool factory interface declared in PJLIB is designed to be extensible. 
    58  * Application can define its own strategy by creating it's own pool factory 
    59  * implementation, and this strategy can be used even by existing library 
    60  * without recompilation. 
    61  * 
    62  * 
    63  * \section PJ_POOL_POLICY_SEC Pool Factory Policy 
    64  * See: \ref PJ_POOL_FACTORY "Pool Factory Policy" 
    65  * 
    66  * A pool factory only defines functions to create and release pool and how 
    67  * to manage pools, but the rest of the functionalities are controlled by 
    68  * policy. A pool policy defines: 
    69  *  - how memory block is allocated and deallocated (the default implementation 
    70  *    allocates and deallocate memory by calling malloc() and free()). 
    71  *  - callback to be called when memory allocation inside a pool fails (the 
    72  *    default implementation will throw PJ_NO_MEMORY_EXCEPTION exception). 
    73  *  - concurrency when creating and releasing pool from/to the factory. 
    74  * 
    75  * A pool factory can be given different policy during creation to make 
    76  * it behave differently. For example, caching pool factory can be configured 
    77  * to allocate and deallocate from a static/contiguous/preallocated memory  
    78  * instead of using malloc()/free(). 
     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 
    79100 *  
    80  * What strategy/factory and what policy to use is not defined by PJLIB, but 
    81  * instead is left to application to make use whichever is most efficient for 
    82  * itself. 
    83  * 
    84  * 
    85  * \section PJ_POOL_POOL_SEC The Pool 
    86  * See: \ref PJ_POOL "Pool" 
    87  * 
     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()! 
     105 * 
     106 * (Note: your mileage may vary, of course. You can see how much PJLIB's 
     107 *  pool improves the performance over malloc()/free() in your target 
     108 *  system by running pjlib-test application). 
     109 * 
     110 * 
     111 * \subsection PJ_POOL_CAVEATS_SUBSEC Caveats 
     112 * 
     113 * There are some caveats though! 
     114 * 
     115 * When creating pool, PJLIB requires applications to specify the initial 
     116 * pool size, and as soon as the pool is created, PJLIB allocates memory 
     117 * from the system by that size. Application designers MUST choose the  
     118 * initial pool size carefully, since choosing too big value will result in 
     119 * wasting system's memory. 
     120 * 
     121 * But the pool can grow. Application designer can specify how the 
     122 * pool will grow in size, by specifying the size increment when creating 
     123 * the pool. 
     124 * 
     125 * The pool, however, <b>cannot</b> shrink! Since there is <b>no</b>  
     126 * function to deallocate memory chunks, there is no way for the pool to  
     127 * release back unused memory to the system.  
     128 * Application designers must be aware that constant memory allocations  
     129 * from pool that has infinite life-time may cause the memory usage of  
     130 * the application to grow over time. 
     131 * 
     132 * 
     133 * \section PJ_POOL_USING_SEC Using Memory Pool 
     134 * 
     135 * This section describes how to use PJLIB's memory pool framework. 
     136 * As we hope the readers will witness, PJLIB's memory pool API is quite 
     137 * straightforward.  
     138 * 
     139 * \subsection PJ_POOL_USING_F Create Pool Factory 
     140 * First, application needs to initialize a pool factory (this normally 
     141 * only needs to be done once in one application). PJLIB provides 
     142 * a pool factory implementation called caching pool (see @ref  
     143 * PJ_CACHING_POOL), and it is initialized by calling #pj_caching_pool_init(). 
     144 * 
     145 * \subsection PJ_POOL_USING_P Create The Pool 
     146 * Then application creates the pool object itself with #pj_pool_create(), 
     147 * specifying among other thing the pool factory where the pool should 
     148 * be created from, the pool name, initial size, and increment/expansion 
     149 * size. 
     150 * 
     151 * \subsection PJ_POOL_USING_M Allocate Memory as Required 
     152 * Then whenever application needs to allocate dynamic memory, it would 
     153 * call #pj_pool_alloc(), #pj_pool_calloc(), or #pj_pool_zalloc() to 
     154 * allocate memory chunks from the pool. 
     155 * 
     156 * \subsection PJ_POOL_USING_DP Destroy the Pool 
     157 * When application has finished with the pool, it should call  
     158 * #pj_pool_release() to release the pool object back to the factory.  
     159 * Depending on the types of the factory, this may release the memory back  
     160 * to the operating system. 
     161 * 
     162 * \subsection PJ_POOL_USING_Dc Destroy the Pool Factory 
     163 * And finally, before application quites, it should deinitialize the 
     164 * pool factory, to make sure that all memory blocks allocated by the 
     165 * factory are released back to the operating system. After this, of  
     166 * course no more memory pool allocation can be requested. 
     167 * 
     168 * \subsection PJ_POOL_USING_EX Example 
     169 * Below is a sample complete program that utilizes PJLIB's memory pool. 
     170 * 
     171 * \code 
     172 
     173   #include <pjlib.h> 
     174 
     175   #define THIS_FILE    "pool_sample.c" 
     176 
     177   static void my_perror(const char *title, pj_status_t status) 
     178   { 
     179        char errmsg[PJ_ERR_MSG_SIZE]; 
     180 
     181        pj_strerror(status, errmsg, sizeof(errmsg)); 
     182        PJ_LOG(1,(THIS_FILE, "%s: %s [status=%d]", title, errmsg, status)); 
     183   } 
     184 
     185   static void pool_demo_1(pj_pool_factory *pfactory) 
     186   { 
     187        unsigned i; 
     188        pj_pool_t *pool; 
     189 
     190        // Must create pool before we can allocate anything 
     191        pool = pj_pool_create(pfactory,  // the factory 
     192                              "pool1",   // pool's name 
     193                              4000,      // initial size 
     194                              4000,      // increment size 
     195                              NULL);     // use default callback. 
     196        if (pool == NULL) { 
     197            my_perror("Error creating pool", PJ_ENOMEM); 
     198            return; 
     199        } 
     200 
     201        // Demo: allocate some memory chunks 
     202        for (i=0; i<1000; ++i) { 
     203            void *p; 
     204 
     205            p = pj_pool_alloc(pool, (pj_rand()+1) % 512); 
     206 
     207            // Do something with p 
     208            ... 
     209 
     210            // Look! No need to free p!! 
     211        } 
     212 
     213        // Done with silly demo, must free pool to release all memory. 
     214        pj_pool_release(pool); 
     215   } 
     216 
     217   int main() 
     218   { 
     219        pj_caching_pool cp; 
     220        pj_status_t status; 
     221 
     222        // Must init PJLIB before anything else 
     223        status = pj_init(); 
     224        if (status != PJ_SUCCESS) { 
     225            my_perror("Error initializing PJLIB", status); 
     226            return 1; 
     227        } 
     228 
     229        // Create the pool factory, in this case, a caching pool. 
     230        pj_caching_pool_init(&cp, &pj_pool_factory_default_policy,  
     231                             1024*1024 ); 
     232 
     233        // Do a demo 
     234        pool_demo_1(&cp.factory); 
     235 
     236        // Done with demos, destroy caching pool before exiting app. 
     237        pj_caching_pool_destroy(&cp); 
     238 
     239        return 0; 
     240   } 
     241 
     242   \endcode 
     243 * 
     244 * More information about pool factory, the pool object, and caching pool 
     245 * can be found on the Module Links below. 
     246 */ 
     247 
     248 
     249/** 
     250 * @defgroup PJ_POOL Memory Pool Object 
     251 * @ingroup PJ_POOL_GROUP 
     252 * @brief 
    88253 * The memory pool is an opaque object created by pool factory. 
    89254 * Application uses this object to request a memory chunk, by calling 
    90  * #pj_pool_alloc or #pj_pool_calloc. When the application has finished using 
    91  * the pool, it must call #pj_pool_release to free all the chunks previously 
     255 * #pj_pool_alloc(), #pj_pool_calloc(), or #pj_pool_zalloc().  
     256 * When the application has finished using 
     257 * the pool, it must call #pj_pool_release() to free all the chunks previously 
    92258 * allocated and release the pool back to the factory. 
    93259 * 
    94  * \section PJ_POOL_THREADING_SEC More on Threading Policies: 
     260 * A memory pool is initialized with an initial amount of memory, which is 
     261 * called a block. Pool can be configured to dynamically allocate more memory  
     262 * blocks when it runs out of memory.  
     263 * 
     264 * The pool doesn't keep track of individual memory allocations 
     265 * by user, and the user doesn't have to free these indidual allocations. This 
     266 * makes memory allocation simple and very fast. All the memory allocated from 
     267 * the pool will be destroyed when the pool itself is destroyed. 
     268 * 
     269 * \section PJ_POOL_THREADING_SEC More on Threading Policies 
    95270 * - By design, memory allocation from a pool is not thread safe. We assumed  
    96271 *   that a pool will be owned by an object, and thread safety should be  
     
    106281 * For some sample codes on how to use the pool, please see: 
    107282 *  - @ref page_pjlib_pool_test 
    108  */ 
    109  
    110 /** 
    111  * @defgroup PJ_POOL Memory Pool. 
    112  * @ingroup PJ_POOL_GROUP 
    113  * @brief 
    114  * A memory pool is initialized with an initial amount of memory, which is 
    115  * called a block. Pool can be configured to dynamically allocate more memory  
    116  * blocks when it runs out of memory. Subsequent memory allocations by user  
    117  * will use up portions of these block.  
    118  * The pool doesn't keep track of individual memory allocations 
    119  * by user, and the user doesn't have to free these indidual allocations. This 
    120  * makes memory allocation simple and very fast. All the memory allocated from 
    121  * the pool will be destroyed when the pool itself is destroyed. 
     283 * 
    122284 * @{ 
    123285 */ 
     
    315477/* **************************************************************************/ 
    316478/** 
    317  * @defgroup PJ_POOL_FACTORY Pool Factory and Policy. 
     479 * @defgroup PJ_POOL_FACTORY Pool Factory and Policy 
    318480 * @ingroup PJ_POOL_GROUP 
    319481 * @brief 
    320  * Pool factory declares an interface to create and destroy pool. There may 
    321  * be several strategies for pool creation, and these strategies should  
    322  * implement the interface defined by pool factory. 
     482 * A pool object must be created through a factory. A factory not only provides 
     483 * generic interface functions to create and release pool, but also provides  
     484 * strategy to manage the life time of pools. One sample implementation,  
     485 * \a pj_caching_pool, can be set to keep the pools released by application for 
     486 * future use as long as the total memory is below the limit. 
     487 *  
     488 * The pool factory interface declared in PJLIB is designed to be extensible. 
     489 * Application can define its own strategy by creating it's own pool factory 
     490 * implementation, and this strategy can be used even by existing library 
     491 * without recompilation. 
    323492 * 
    324493 * \section PJ_POOL_FACTORY_ITF Pool Factory Interface 
     
    329498 * 
    330499 * \section PJ_POOL_FACTORY_POL Pool Factory Policy. 
     500 * 
     501 * A pool factory only defines functions to create and release pool and how 
     502 * to manage pools, but the rest of the functionalities are controlled by 
     503 * policy. A pool policy defines: 
     504 *  - how memory block is allocated and deallocated (the default implementation 
     505 *    allocates and deallocate memory by calling malloc() and free()). 
     506 *  - callback to be called when memory allocation inside a pool fails (the 
     507 *    default implementation will throw PJ_NO_MEMORY_EXCEPTION exception). 
     508 *  - concurrency when creating and releasing pool from/to the factory. 
     509 * 
     510 * A pool factory can be given different policy during creation to make 
     511 * it behave differently. For example, caching pool factory can be configured 
     512 * to allocate and deallocate from a static/contiguous/preallocated memory  
     513 * instead of using malloc()/free(). 
     514 *  
     515 * What strategy/factory and what policy to use is not defined by PJLIB, but 
     516 * instead is left to application to make use whichever is most efficient for 
     517 * itself. 
     518 * 
    331519 * The pool factory policy controls the behaviour of memory factories, and 
    332520 * defines the following interface: 
     
    530718 
    531719/** 
    532  * @defgroup PJ_CACHING_POOL Caching Pool Factory. 
     720 * @defgroup PJ_CACHING_POOL Caching Pool Factory 
    533721 * @ingroup PJ_POOL_GROUP 
    534722 * @brief 
  • pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h

    r690 r691  
    25172517 
    25182518 
     2519 
     2520/** 
     2521 * Get currently active sound devices. If sound devices has not been created 
     2522 * (for example when pjsua_start() is not called), it is possible that 
     2523 * the function returns PJ_SUCCESS with -1 as device IDs. 
     2524 * 
     2525 * @param capture_dev   On return it will be filled with device ID of the  
     2526 *                      capture device. 
     2527 * @param playback_dev  On return it will be filled with device ID of the  
     2528 *                      device ID of the playback device. 
     2529 * 
     2530 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     2531 */ 
     2532PJ_DECL(pj_status_t) pjsua_get_snd_dev(int *capture_dev, 
     2533                                       int *playback_dev); 
     2534 
     2535 
    25192536/** 
    25202537 * Select or change sound device. Application may call this function at 
Note: See TracChangeset for help on using the changeset viewer.