diff options
author | Anders Broman <anders.broman@ericsson.com> | 2005-12-18 18:15:24 +0000 |
---|---|---|
committer | Anders Broman <anders.broman@ericsson.com> | 2005-12-18 18:15:24 +0000 |
commit | 476059c8b8bb5f26164b1228b4006a2b8922aa2d (patch) | |
tree | 40628e4910c22ec6832f8496d7cb7db65be5e98a /doc/README.malloc | |
parent | e3e3e3f5f8e6c17e4ef18ad3dc02080c69d3dc8c (diff) |
From Martin Warnes
Attached a small patch to top level Makefile.am to include the recently
added diamter data files chargecontrol.xml and TGPPSh.xml
From jaaap Keuter:
I've polished up the README.malloc describing ememified memory management. It's basically the same information, but made a bit more accessable. All this in response to bug 511
svn path=/trunk/; revision=16845
Diffstat (limited to 'doc/README.malloc')
-rw-r--r-- | doc/README.malloc | 114 |
1 files changed, 71 insertions, 43 deletions
diff --git a/doc/README.malloc b/doc/README.malloc index 9c4d6ea90a..9b1305641d 100644 --- a/doc/README.malloc +++ b/doc/README.malloc @@ -1,47 +1,75 @@ -$Id$ +$Id:$ -In order to make memory management easier and to reduce the probability of memory leaks ethereal provides its own memory management API. -This API is implemented inside epan/emem.c and provides memory allocation functions where the allocated memory is automatically freed at certain points. +1. Introduction + +In order to make memory management easier and to reduce the probability of +memory leaks ethereal provides its own memory management API. This API is +implemented inside epan/emem.c and provides memory allocation functions +where the allocated memory is automatically freed at certain points. If you use these functions you will no longer need to keep track of when and -where to free any dynamically allocated memory, the memory will automatically be freed at the appropriate time. - - -Using these functions will greatly elevate the probability that your code will not leak memory so do use them where appropriate. - - - -There are two sets of fucntions with different allocation/free scope: -ephemeral: -ep_... which allocates memory that will be automatically freed once the - current packet dissection completes. These functions are useful - for situations where you just want a temporary buffer that should stay - around for a short while. - Do not use these functions if you need persistent allocations where - the data is to still be available in some later packet. -seasonal: -se_... which allocates memory that will stay around a lot longer but will be - automatically freed once the current capture is closed and ethereal - opens a new capture (either by reading a new capture file or by starting - a new capture on some interface). - These functions are useful for allocations with longer scope for example - if you need some buffers or data to keep statemanagement between packets. - - -These two allocation scopes provide several useful functions : -.._alloc() : allocate a chunk of memory with ep/se scope. -.._alloc0() : allocate a chunk of memory and fill it with 0. -.._strdup() : equivalent to strdup() -.._strndup(s,n) : allocate a chunk of size n+1 and copy s into it -.._memdup(s,n) : allocate n chunk and copy into it n bytes starting at s - -.._strdup_printf() : will calculate the size of the formated string allocate a chunk for it and format the string -.._alloc_array(t,n): will allocate an array of n elements of type t -ep_strsplit(): will split a string based on a certain separator returning an array of strings - -Stack management: -ep_stack_new() : creates a stack -ep_stack_push() : pushes an element into the stack -ep_stack_pop() : pops an element from the stack -ep_stack_peek() : returns the top element of the stack without popping it +where to free any dynamically allocated memory, the memory will +automatically be freed at the appropriate time. + +Using these functions will greatly elevate the probability that your code +will not leak memory so do use them where appropriate. + +2. The allocation types + +There are two sets of functions with different allocation temporal scopes: + * ephemeral (ep_...) + * seasonal (se_...) + +2.1 Ephemeral allocations + +The ephemeral functions allocate memory that will be automatically freed +once the current packet dissection completes. These functions are useful for +situations where you just want a temporary buffer that should stay around for +a short while. Do not use these functions if you need persistent allocations +where the data is to still be available in some later packet. + +2.2 Seasonal allocations + +The seasonal functions allocate memory that will stay around a lot longer +but will be automatically freed once the current capture is closed and +Ethereal opens a new capture (either by reading a new capture file or by +starting a new capture on some interface). These functions are useful for +allocations with longer scope for example if you need some buffers or data to +keep state between packets. + +3 The API + +For a detailed description of the functions please refer to the header file +epan/emem.h + +3.1 Common memory allocation functions + +.._alloc(n) : allocate a chunk of memory of size n with ep/se scope. +ep_new(t) : allocate a single element of type t. +.._alloc_array(t,n): will allocate an array of n elements of type t. + +.._alloc0(n) : allocate a chunk of memory of size n and fill it with 0. +ep_new0(t) : allocate a single element of type t and fill it with 0. + +3.2 String related functions + +.._strdup(s) : equivalent to strdup(s) with ep/se scope. +.._strndup(s,n) : allocate a chunk of size n+1 and copy s into it. +.._memdup(s,n) : allocate n chunk and copy into it n bytes starting at s. + +.._strdup_printf() : will calculate the size of the formated string, allocate + a chunk for it and format the string. +.._strdup_vprintf() : will calculate the size of the formated string, + allocate a chunk for it and format the string. + +ep_strsplit(): will split a string based on a certain separator returning an + array of strings. + +3.3 Stack related functions + +ep_stack_new() : creates an ephemeral stack. +ep_stack_push() : pushes an element into the stack. +ep_stack_pop() : pops an element from the stack. +ep_stack_peek() : returns the top element of the stack without popping it. + |