Changeset 691
- Timestamp:
- Aug 25, 2006 12:41:05 PM (18 years ago)
- Location:
- pjproject/trunk
- Files:
-
- 6 edited
Legend:
- Unmodified
- Added
- Removed
-
pjproject/trunk/pjlib/docs/doxygen.cfg
r690 r691 18 18 # by quotes) that should identify the project. 19 19 20 PROJECT_NAME = "PJLIB Open Source"20 PROJECT_NAME = "PJLIB Reference" 21 21 22 22 # The PROJECT_NUMBER tag can be used to enter a project or revision number. -
pjproject/trunk/pjlib/docs/footer.html
r690 r691 2 2 <hr><center> 3 3 PJLIB Open Source, high performance, small footprint, and very very portable framework<br> 4 (C)200 3-2006 Benny Prijono4 (C)2001-2006 Benny Prijono 5 5 </center> 6 6 -
pjproject/trunk/pjlib/include/pj/doxygen.h
r690 r691 394 394 * Enjoy using PJLIB! 395 395 * 396 * Benny Prijono < bennylp at pj project dot net>396 * Benny Prijono < bennylp at pjsip dot org > 397 397 */ 398 398 -
pjproject/trunk/pjlib/include/pj/ioqueue.h
r622 r691 60 60 61 61 /** 62 * @defgroup PJ_IOQUEUE I /O Event Dispatching Queue62 * @defgroup PJ_IOQUEUE IOQueue: I/O Event Dispatching with Proactor Pattern 63 63 * @ingroup PJ_IO 64 64 * @{ -
pjproject/trunk/pjlib/include/pj/pool.h
r622 r691 39 39 40 40 /** 41 * @defgroup PJ_POOL_GROUP Memory Pool Management41 * @defgroup PJ_POOL_GROUP Fast Memory Pool 42 42 * @ingroup PJ 43 43 * @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 56 51 * 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 79 100 * 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 88 253 * The memory pool is an opaque object created by pool factory. 89 254 * 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 92 258 * allocated and release the pool back to the factory. 93 259 * 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 95 270 * - By design, memory allocation from a pool is not thread safe. We assumed 96 271 * that a pool will be owned by an object, and thread safety should be … … 106 281 * For some sample codes on how to use the pool, please see: 107 282 * - @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 * 122 284 * @{ 123 285 */ … … 315 477 /* **************************************************************************/ 316 478 /** 317 * @defgroup PJ_POOL_FACTORY Pool Factory and Policy .479 * @defgroup PJ_POOL_FACTORY Pool Factory and Policy 318 480 * @ingroup PJ_POOL_GROUP 319 481 * @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. 323 492 * 324 493 * \section PJ_POOL_FACTORY_ITF Pool Factory Interface … … 329 498 * 330 499 * \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 * 331 519 * The pool factory policy controls the behaviour of memory factories, and 332 520 * defines the following interface: … … 530 718 531 719 /** 532 * @defgroup PJ_CACHING_POOL Caching Pool Factory .720 * @defgroup PJ_CACHING_POOL Caching Pool Factory 533 721 * @ingroup PJ_POOL_GROUP 534 722 * @brief -
pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h
r690 r691 2517 2517 2518 2518 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 */ 2532 PJ_DECL(pj_status_t) pjsua_get_snd_dev(int *capture_dev, 2533 int *playback_dev); 2534 2535 2519 2536 /** 2520 2537 * Select or change sound device. Application may call this function at
Note: See TracChangeset
for help on using the changeset viewer.