Eina_Cow_Group(3)

NAME
Eina_Cow_Group - Copy On Write

 - These functions provide some helper for a pseudo Copy-On-Write mechanism.

SYNOPSIS

  Macros
#define EINA_COW_WRITE_BEGIN(Cow, Read, Write_Type, Write)
Definition for the macro to setup a writeable pointer from a const one.
#define EINA_COW_WRITE_END(Cow, Read, Write)
Definition for the macro to close the writeable pointer.
#define EINA_COW_WRITE_END_NOGC(Cow, Read, Write)
Definition for the macro to close the writeable pointer without triggering the GC.

  Typedefs
typedef struct _Eina_Cow Eina_Cow
Type for Eina_Cow pool.
typedef void Eina_Cow_Data
Type of the returned pointer to simplify some reading.

  Functions
EINA_API Eina_Cow * eina_cow_add (const char *name, unsigned int struct_size, unsigned int step, const void *default_value, Eina_Bool gc)
Instantiates a new Eina_Cow pool.
EINA_API void eina_cow_del (Eina_Cow *cow)
Destroys an Eina_Cow pool and all the allocated memory.
EINA_API const Eina_Cow_Data * eina_cow_alloc (Eina_Cow *cow)
Returns an initialized pointer from the pool.
EINA_API void eina_cow_free (Eina_Cow *cow, const Eina_Cow_Data **data)
Frees a pointer from the pool.
EINA_API void * eina_cow_write (Eina_Cow *cow, const Eina_Cow_Data *const *src)
Gets a writeable pointer from a const pointer.
EINA_API void eina_cow_done (Eina_Cow *cow, const Eina_Cow_Data *const *dst, const void *data, Eina_Bool needed_gc)
Sets back a pointer into read only.
EINA_API void eina_cow_memcpy (Eina_Cow *cow, const Eina_Cow_Data *const *dst, const Eina_Cow_Data *src)
Makes the destination contain the same thing as the source pointer.
EINA_API Eina_Bool eina_cow_gc (Eina_Cow *cow)
Tries to find entries that have the same content and update them.

Detailed Description

These functions provide some helper for a pseudo Copy-On-Write mechanism. Eina_Cow will return a const memory pointer to some default value that you will be able to change only by requesting a writable pointer. Later on a garbage collector can come online and try to merge back some of those pointers.

Since
    1.8.0

Macro Definition Documentation

  #define EINA_COW_WRITE_BEGIN(Cow, Read, Write_Type, Write)
Value:

  do                                                                      {                                                                         Write_Type *Write;                                                                                                                              Write = eina_cow_write(Cow, ((const Eina_Cow_Data**)&(Read)));

Definition for the macro to setup a writeable pointer from a const one.

Parameters
    Cow The Eina_Cow where the const pointer came from.
    Read The const pointer to get a writable handler from.
    Write_Type The type of the pointer you want to write to.
    Write The name of the variable where to put the writeable pointer to.

Since
    1.8.0

Note
    This macro opens a C scope that is expected to be closed by EINA_COW_WRITE_END().

  #define EINA_COW_WRITE_END(Cow, Read, Write)
Value:

      eina_cow_done(Cow, ((const Eina_Cow_Data**)&(Read)), Write,                       EINA_TRUE);                                             }                                                                     while (0);

Definition for the macro to close the writeable pointer.

Parameters
    Cow The Eina_Cow where the const pointer came from.
    Read The const pointer to get a writable handler from.
    Write The name of the variable where to put the writeable pointer to.

Since
    1.8.0

Note
    This macro closes the scope opened by EINA_COW_WRITE_BEGIN().

  #define EINA_COW_WRITE_END_NOGC(Cow, Read, Write)
Value:

      eina_cow_done(Cow, ((const Eina_Cow_Data**)&(Read)), Write,                          EINA_FALSE);                                            }                                                                     while (0);

Definition for the macro to close the writeable pointer without triggering the GC.

Parameters
    Cow The Eina_Cow where the const pointer came from.
    Read The const pointer to get a writable handler from.
    Write The name of the variable where to put the writeable pointer to.

Since
    1.8.0

Note
    This macro closes the scope opened by EINA_COW_WRITE_BEGIN().

Function Documentation

  EINA_API Eina_Cow* eina_cow_add (const char * name, unsigned int struct_size, unsigned int step, const void * default_value, Eina_Bool gc)

Instantiates a new Eina_Cow pool.

Parameters
    name The name of this pool, used for debugging.
    struct_size The size of the object from this pool.
    step How many objects to allocate when the pool gets empty.
    default_value The default value returned by this pool.
    gc Is it possible to run garbage collection on this pool.

Returns
    A valid new Eina_Cow, or NULL on error.

References eina_hash_new(), eina_hash_pointer_new(), EINA_MAGIC_SET, eina_mempool_add(), eina_mempool_alignof(), EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, ERR, and INF.

  EINA_API void eina_cow_del (Eina_Cow * cow)

Destroys an Eina_Cow pool and all the allocated memory.

Parameters
    cow The pool to destroy

References eina_hash_free(), and eina_mempool_del().

Referenced by evas_shutdown().

  EINA_API const Eina_Cow_Data* eina_cow_alloc (Eina_Cow * cow)

Returns an initialized pointer from the pool.

Parameters
    cow The pool to take things from.

Returns
    A pointer to the new pool instance

  EINA_API void eina_cow_free (Eina_Cow * cow, const Eina_Cow_Data ** data)

Frees a pointer from the pool.

Parameters
    cow The pool to gave back memory to.
    data The data to give back.

Note
    To simplify the caller code *data will point to the default read only state after the call to this function.

References EINA_MAGIC_NONE, EINA_MAGIC_SET, and eina_mempool_free().

Referenced by eina_cow_memcpy().

  EINA_API void* eina_cow_write (Eina_Cow * cow, const Eina_Cow_Data *const * src)

Gets a writeable pointer from a const pointer.

Parameters
    cow The pool the pointer came from.
    src The pointer you want to write to.

Note
    This function is not thread safe.

References EINA_FALSE, EINA_MAGIC_SET, eina_mempool_malloc(), and ERR.

  EINA_API void eina_cow_done (Eina_Cow * cow, const Eina_Cow_Data *const * dst, const void * data, Eina_Bool needed_gc)

Sets back a pointer into read only.

Parameters
    cow The pool the pointer came from.
    dst The read only version of the pointer.
    data The pointer to which data was written to.
    needed_gc Does this pool need to be garbage collected?

Note
    This function is not thread safe.

References ERR.

  EINA_API void eina_cow_memcpy (Eina_Cow * cow, const Eina_Cow_Data *const * dst, const Eina_Cow_Data * src)

Makes the destination contain the same thing as the source pointer.

Parameters
    cow The pool the pointers came from.
    dst The destination to update.
    src The source of information to copy.

References eina_cow_free().

  EINA_API Eina_Bool eina_cow_gc (Eina_Cow * cow)

Tries to find entries that have the same content and update them.

Parameters
    cow The cow to try to compact.

Returns
    EINA_TRUE if something was compacted, EINA_FALSE if nothing was.

There is no guaranty in the time it will require, but should remain low. It does run a hash function on all possible common structures trying to find the one that matches and merge them into one pointer.

References EINA_FALSE, eina_hash_iterator_data_new(), eina_hash_population(), eina_iterator_free(), eina_iterator_next(), and EINA_TRUE.

Author

Generated automatically by Doxygen for EFL from the source code.