Commit 9b32a359 authored by Pekka Pessi's avatar Pekka Pessi

su_alloc.c: su_home_create() is now an alias to su_home_new(sizeof(su_home_t))

Improve document, too.

darcs-hash:20061121193823-65a35-618b24dfde58f9e1ee606616924dd161696ab515.gz
parent 6dbc1f0d
...@@ -101,10 +101,13 @@ ...@@ -101,10 +101,13 @@
* su_free(tophome, ctx); * su_free(tophome, ctx);
* @endcode * @endcode
* *
* @note * @note
* The su_home_create() and su_home_destroy() are deprecated. The *
* function su_home_create() creates a home object with infinite reference * The su_home_destroy() function is deprecated as it does not free the home
* count. Likewise, su_home_init() does the same. * object itself.
*
* The function su_home_init() initializes a home object with infinite
* reference count. It must be deinitialized with su_home_deinit().
* *
* @section su_home_destructor_usage Destructors * @section su_home_destructor_usage Destructors
* *
...@@ -113,7 +116,7 @@ ...@@ -113,7 +116,7 @@
* besides memory. The destructor function will be called when the reference * besides memory. The destructor function will be called when the reference
* count of home reaches zero (upon calling su_home_unref()) or the home * count of home reaches zero (upon calling su_home_unref()) or the home
* object is otherwise deinitialized (calling su_home_deinit() on * object is otherwise deinitialized (calling su_home_deinit() on
* stack-derived objects). * objects allocated from stack).
* *
* @section su_home_move_example Combining Allocations * @section su_home_move_example Combining Allocations
* *
...@@ -502,7 +505,9 @@ void *sub_alloc(su_home_t *home, ...@@ -502,7 +505,9 @@ void *sub_alloc(su_home_t *home,
* *
* Create a home object used to collect multiple memory allocations under * Create a home object used to collect multiple memory allocations under
* one handle. The memory allocations made using this home object is freed * one handle. The memory allocations made using this home object is freed
* either when this home is destroyed. * either when this home is destroyed.
*
* The maximum @a size of a home object is INT_MAX (2 gigabytes).
* *
* @param size size of home object * @param size size of home object
* *
...@@ -848,50 +853,44 @@ void su_home_check_blocks(su_block_t const *b) ...@@ -848,50 +853,44 @@ void su_home_check_blocks(su_block_t const *b)
* *
* The function su_home_create() creates a home object. A home object is * The function su_home_create() creates a home object. A home object is
* used to collect multiple memory allocations, so that they all can be * used to collect multiple memory allocations, so that they all can be
* freed by calling su_home_destroy(). * freed by calling su_home_unref().
* *
* @return This function returns a pointer to an @c su_home_t object, or @c * @return This function returns a pointer to an @c su_home_t object, or @c
* NULL upon an error. * NULL upon an error.
*
* @deprecated
* Use su_home_new() or su_home_clone() instead of su_home_create().
*/ */
su_home_t *su_home_create(void) su_home_t *su_home_create(void)
{ {
su_home_t *home = su_salloc(NULL, sizeof (*home)); return su_home_new(sizeof(su_home_t));
if (home) {
su_home_init(home);
}
return home;
} }
/** Deinitialize a home object /** Deinitialize a home object
* *
* The function su_home_destroy() frees a home object, and all memory * The function su_home_destroy() frees all memory blocks associated with a
* blocks associated with it. * home object. Note that the home object is not freed.
* *
* @param home pointer to a home object * @param home pointer to a home object
* *
* @deprecated * @deprecated
* Use su_home_deinit() instead of su_home_destroy(). * su_home_destroy() is included for backwards compatibility only. Use
* su_home_unref() instead of su_home_destroy().
*/ */
void su_home_destroy(su_home_t *home) void su_home_destroy(su_home_t *home)
{ {
su_home_deinit(home); su_home_deinit(home);
/* free(home); - what if this is cloned one? */ /* XXX - home itself is not destroyed */
} }
/** Initialize an su_home_t object. /** Initialize an su_home_t struct.
* *
* The function su_home_init() initializes an object derived from su_home_t. * The function su_home_init() initializes an su_home_t structure. It can be
* used when the home structure is allocated from stack.
* *
* @param home pointer to home object * @param home pointer to home object
* *
* @return * @retval 0 when successful
* The function su_home_init() returns 0 when successful, * @retval -1 upon an error.
* or -1 upon an error. *
* @sa SU_HOME_INIT(), su_home_deinit(), su_home_new(), su_home_clone()
*/ */
int su_home_init(su_home_t *home) int su_home_init(su_home_t *home)
{ {
...@@ -958,9 +957,12 @@ void _su_home_deinit(su_home_t *home) ...@@ -958,9 +957,12 @@ void _su_home_deinit(su_home_t *home)
/** Free memory blocks allocated through home. /** Free memory blocks allocated through home.
* *
* The function @c su_home_deinit() frees the memory blocks associated with * The function @c su_home_deinit() frees the memory blocks associated with
* the home object. * the home object allocated otherwise. It does not free the home object
* itself. Use su_home_unref() to free the home object.
* *
* @param home pointer to home object * @param home pointer to home object
*
* @sa su_home_init()
*/ */
void su_home_deinit(su_home_t *home) void su_home_deinit(su_home_t *home)
{ {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment