## e-memory

e-memory

## Synopsis

                        EMemChunk;
    EMemChunk *         e_memchunk_new                      (gint atomcount,
                                                             gint atomsize);
    gpointer            e_memchunk_alloc                    (EMemChunk *m);
    gpointer            e_memchunk_alloc0                   (EMemChunk *m);
    void                e_memchunk_free                     (EMemChunk *m,
                                                             gpointer mem);
    void                e_memchunk_empty                    (EMemChunk *m);
    void                e_memchunk_clean                    (EMemChunk *m);
    void                e_memchunk_destroy                  (EMemChunk *m);
                        EMemPool;
    enum                EMemPoolFlags;
    EMemPool *          e_mempool_new                       (gint blocksize,
                                                             gint threshold,
                                                             EMemPoolFlags flags);
    gpointer            e_mempool_alloc                     (EMemPool *pool,
                                                             gint size);
    gchar *             e_mempool_strdup                    (EMemPool *pool,
                                                             const gchar *str);
    void                e_mempool_flush                     (EMemPool *pool,
                                                             gint freeall);
    void                e_mempool_destroy                   (EMemPool *pool);
                        EStrv;
    EStrv *             e_strv_new                          (gint size);
    EStrv *             e_strv_set_ref                      (EStrv *strv,
                                                             gint index,
                                                             gchar *str);
    EStrv *             e_strv_set_ref_free                 (EStrv *strv,
                                                             gint index,
                                                             gchar *str);
    EStrv *             e_strv_set                          (EStrv *strv,
                                                             gint index,
                                                             const gchar *str);
    EStrv *             e_strv_pack                         (EStrv *strv);
    const gchar *       e_strv_get                          (EStrv *strv,
                                                             gint index);
    void                e_strv_destroy                      (EStrv *strv);
                        EPoolv;
    EPoolv *            e_poolv_new                         (guint size);
    EPoolv *            e_poolv_cpy                         (EPoolv *dest,
                                                             const EPoolv *src);
    EPoolv *            e_poolv_set                         (EPoolv *poolv,
                                                             gint index,
                                                             gchar *str,
                                                             gint freeit);
    const gchar *       e_poolv_get                         (EPoolv *poolv,
                                                             gint index);
    void                e_poolv_destroy                     (EPoolv *poolv);

## Description

## Details

### EMemChunk

    typedef struct _EMemChunk EMemChunk;

### e_memchunk_new ()

    EMemChunk *         e_memchunk_new                      (gint atomcount,
                                                             gint atomsize);

Create a new memchunk header. Memchunks are an efficient way to allocate and deallocate identical sized blocks of memory quickly, and space efficiently.

e_memchunks are effectively the same as gmemchunks, only faster (much), and they use less memory overhead for housekeeping.

`atomcount` : | The number of atoms stored in a single malloc'd block of memory.
`atomsize` : | The size of each allocation.
Returns : | The new header.

### e_memchunk_alloc ()

    gpointer            e_memchunk_alloc                    (EMemChunk *m);

`m` : |
Returns : |

### e_memchunk_alloc0 ()

    gpointer            e_memchunk_alloc0                   (EMemChunk *m);

`m` : |
Returns : |

### e_memchunk_free ()

    void                e_memchunk_free                     (EMemChunk *m,
                                                             gpointer mem);

Free a single atom back to the free pool of atoms in the given memchunk.

`m` : |
`mem` : | Address of atom to free.

### e_memchunk_empty ()

    void                e_memchunk_empty                    (EMemChunk *m);

Clean out the memchunk buffers. Marks all allocated memory as free blocks, but does not give it back to the system. Can be used if the memchunk is to be used repeatedly.

`m` : |

### e_memchunk_clean ()

    void                e_memchunk_clean                    (EMemChunk *m);

Scan all empty blocks and check for blocks which can be free'd back to the system.

This routine may take a while to run if there are many allocated memory blocks (if the total number of allocations is many times greater than atomcount).

`m` : |

### e_memchunk_destroy ()

    void                e_memchunk_destroy                  (EMemChunk *m);

Free the memchunk header, and all associated memory.

`m` : |

### EMemPool

    typedef struct _EMemPool EMemPool;

### enum EMemPoolFlags

    typedef enum {
    	E_MEMPOOL_ALIGN_STRUCT = 0,	/* allocate to native structure alignment */
    	E_MEMPOOL_ALIGN_WORD = 1,	/* allocate to words - 16 bit alignment */
    	E_MEMPOOL_ALIGN_BYTE = 2,	/* allocate to bytes - 8 bit alignment */
    	E_MEMPOOL_ALIGN_MASK = 3	/* which bits determine the alignment information */
    } EMemPoolFlags;

### e_mempool_new ()

    EMemPool *          e_mempool_new                       (gint blocksize,
                                                             gint threshold,
                                                             EMemPoolFlags flags);

Create a new mempool header. Mempools can be used to efficiently allocate data which can then be freed as a whole.

Mempools can also be used to efficiently allocate arbitrarily aligned data (such as strings) without incurring the space overhead of aligning each allocation (which is not required for strings).

However, each allocation cannot be freed individually, only all or nothing.

`blocksize` : | The base blocksize to use for all system alocations.
`threshold` : | If the allocation exceeds the threshold, then it is allocated separately and stored in a separate list.
`flags` : | Alignment options: E_MEMPOOL_ALIGN_STRUCT uses native struct alignment, E_MEMPOOL_ALIGN_WORD aligns to 16 bits (2 bytes), and E_MEMPOOL_ALIGN_BYTE aligns to the nearest byte. The default is to align to native structures.
Returns : |

### e_mempool_alloc ()

    gpointer            e_mempool_alloc                     (EMemPool *pool,
                                                             gint size);

Allocate a new data block in the mempool. Size will be rounded up to the mempool's alignment restrictions before being used.

`pool` : |
`size` : |
Returns : |

### e_mempool_strdup ()

    gchar *             e_mempool_strdup                    (EMemPool *pool,
                                                             const gchar *str);

`pool` : |
`str` : |
Returns : |

### e_mempool_flush ()

    void                e_mempool_flush                     (EMemPool *pool,
                                                             gint freeall);

Flush used memory and mark allocated blocks as free.

If `freeall` is TRUE, then all allocated blocks are free'd as well. Otherwise only blocks above the threshold are actually freed, and the others are simply marked as empty.

`pool` : |
`freeall` : | Free all system allocated blocks as well.

### e_mempool_destroy ()

    void                e_mempool_destroy                   (EMemPool *pool);

Free all memory associated with a mempool.

`pool` : |

### EStrv

    typedef struct _EStrv EStrv;

### e_strv_new ()

    EStrv *             e_strv_new                          (gint size);

Create a new strv (string array) header. strv's can be used to create and work with arrays of strings that can then be compressed into a space-efficient static structure. This is useful where a number of strings are to be stored for lookup, and not generally edited afterwards.

The size limit is currently 254 elements. This will probably not change as arrays of this size suffer significant performance penalties when looking up strings with high indices.

`size` : | The number of elements in the strv. Currently this is limited to 254 elements.
Returns : |

### e_strv_set_ref ()

    EStrv *             e_strv_set_ref                      (EStrv *strv,
                                                             gint index,
                                                             gchar *str);

Set a string array element by reference. The string is not copied until the array is packed.

If `strv` has been packed, then it is unpacked ready for more inserts, and should be packed again once finished with. The memory used by the original `strv` is not freed until the new strv is packed, or freed itself.

`strv` : |
`index` : |
`str` : |
Returns : | A new EStrv if the strv has already been packed, otherwise `strv`.

### e_strv_set_ref_free ()

    EStrv *             e_strv_set_ref_free                 (EStrv *strv,
                                                             gint index,
                                                             gchar *str);

Set a string by reference, similar to set_ref, but also free the string when finished with it. The string is not copied until the strv is packed, and not at all if the index is overwritten.

`strv` : |
`index` : |
`str` : |
Returns : | `strv` if already unpacked, otherwise an packed EStrv.

### e_strv_set ()

    EStrv *             e_strv_set                          (EStrv *strv,
                                                             gint index,
                                                             const gchar *str);

Set a string array reference. The string `str` is copied into the string array at location `index`.

If `strv` has been packed, then it is unpacked ready for more inserts, and should be packed again once finished with.

`strv` : |
`index` : |
`str` : |
Returns : | A new EStrv if the strv has already been packed, otherwise `strv`.

### e_strv_pack ()

    EStrv *             e_strv_pack                         (EStrv *strv);

Pack the `strv` into a space efficient structure for later lookup.

All strings are packed into a single allocated block, separated by single \0 characters, together with a count byte.

`strv` : |
Returns : |

### e_strv_get ()

    const gchar *       e_strv_get                          (EStrv *strv,
                                                             gint index);

Retrieve a string by index. This function works identically on both packed and unpacked strv's, although may be much slower on a packed strv.

`strv` : |
`index` : |
Returns : |

### e_strv_destroy ()

    void                e_strv_destroy                      (EStrv *strv);

Free a strv and all associated memory. Works on packed or unpacked strv's.

`strv` : |

### EPoolv

    typedef struct _EPoolv EPoolv;

### e_poolv_new ()

    EPoolv *            e_poolv_new                         (guint size);

create a new poolv (string vector which shares a global string pool). poolv's can be used to work with arrays of strings which save memory by eliminating duplicated allocations of the same string.

this is useful when you have a log of read-only strings that do not go away and are duplicated a lot (such as email headers).

we should probably in the future ref count the strings contained in the hash table, but for now let's not.

`size` : |
Returns : | new pooled string vector

### e_poolv_cpy ()

    EPoolv *            e_poolv_cpy                         (EPoolv *dest,
                                                             const EPoolv *src);

Copy the contents of a pooled string vector

`dest` : | destination pooled string vector
`src` : | source pooled string vector
Returns : | `dest`, which may be re-allocated if the strings are different lengths.

### e_poolv_set ()

    EPoolv *            e_poolv_set                         (EPoolv *poolv,
                                                             gint index,
                                                             gchar *str,
                                                             gint freeit);

Set a string vector reference. If the caller will no longer be referencing the string, freeit should be TRUE. Otherwise, this will duplicate the string if it is not found in the pool.

`poolv` : | pooled string vector
`index` : | index in vector of string
`str` : | string to set
`freeit` : | whether the caller is releasing its reference to the string
Returns : | `poolv`

### e_poolv_get ()

    const gchar *       e_poolv_get                         (EPoolv *poolv,
                                                             gint index);

Retrieve a string by index. This could possibly just be a macro.

Since the pool is never freed, this string does not need to be duplicated, but should not be modified.

`poolv` : | pooled string vector
`index` : | index in vector of string
Returns : | string at that index.

### e_poolv_destroy ()

    void                e_poolv_destroy                     (EPoolv *poolv);

Free a pooled string vector. This doesn't free the strings from the vector, however.

`poolv` : | pooled string vector to free