Copy On Write
Eina » Tools

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

## 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

## EINA_COW_WRITE_BEGIN

#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)));
eina_cow_write
EINA_API void * eina_cow_write(Eina_Cow *cow, const Eina_Cow_Data *const *data)
Gets a writeable pointer from a const pointer.
Definition eina_cow.c:455
Eina_Cow_Data
void Eina_Cow_Data
Type of the returned pointer to simplify some reading.
Definition eina_cow.h:52

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

Parameters

  [in,out] | Cow | The Eina_Cow where the const pointer came from.
  [in] | Read | The const pointer to get a writable handler from.
  [in] | Write_Type | The type of the pointer you want to write to.
  [in] | 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().

Referenced by evas_object_image_reload(), evas_object_image_size_set(), evas_object_image_source_visible_set(), and evas_object_map_set().

## 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);
eina_cow_done
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.
Definition eina_cow.c:539
EINA_TRUE
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition eina_types.h:539

Definition for the macro to close the writeable pointer.

Parameters

  [in,out] | Cow | The Eina_Cow where the const pointer came from.
  [in] | Read | The const pointer to get a writable handler from.
  [in] | 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().

Referenced by evas_object_image_reload(), evas_object_image_size_set(), evas_object_image_source_visible_set(), and evas_object_map_set().

## EINA_COW_WRITE_END_NOGC

#define EINA_COW_WRITE_END_NOGC | ( |  | Cow,
|  |  | Read,
|  |  | Write )

Value:
eina_cow_done(Cow, ((const Eina_Cow_Data**)&(Read)), Write, \
EINA_FALSE); \
} \
while (0);
EINA_FALSE
#define EINA_FALSE
boolean value FALSE (numerical value 0)
Definition eina_types.h:533

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

Parameters

  [in,out] | Cow | The Eina_Cow where the const pointer came from.
  [in] | Read | The const pointer to get a writable handler from.
  [in] | 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_cow_add()

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

  [in] | name | The name of this pool, used for debugging.
  [in] | struct_size | The size of the object from this pool.
  [in] | step | How many objects to allocate when the pool gets empty.
  [in] | default_value | The default value returned by this pool.
  [in] | 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.

Referenced by edje_init().

## eina_cow_del()

EINA_API void eina_cow_del | ( | Eina_Cow * | cow | ) |

Destroys an Eina_Cow pool and all the allocated memory.

Parameters

  [in] | cow | The pool to destroy

References eina_hash_free(), and eina_mempool_del().

Referenced by edje_init(), and evas_shutdown().

## eina_cow_alloc()

EINA_API const Eina_Cow_Data * eina_cow_alloc | ( | Eina_Cow * | cow | ) |

Returns an initialized pointer from the pool.

Parameters

  [in] | cow | The pool to take things from.

Returns
  A pointer to the new pool instance

## eina_cow_free()

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

Frees a pointer from the pool.

Parameters

  [in,out] | cow | The pool to gave back memory to.
  [in] | 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, and EINA_MAGIC_SET.

Referenced by eina_cow_memcpy().

## eina_cow_write()

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

Gets a writeable pointer from a const pointer.

Parameters

  [in,out] | cow | The pool the pointer came from.
  [in] | src | The pointer you want to write to.

Note
  This function is not thread safe.

References EINA_FALSE, EINA_MAGIC_SET, and ERR.

## eina_cow_done()

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

  [in,out] | cow | The pool the pointer came from.
  [in] | dst | The read only version of the pointer.
  [in] | data | The pointer to which data was written to.
  [in] | needed_gc | Does this pool need to be garbage collected?

Note
  This function is not thread safe.

References ERR.

## eina_cow_memcpy()

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

  [in,out] | cow | The pool the pointers came from.
  [in] | dst | The destination to update.
  [in] | src | The source of information to copy.

References eina_cow_free().

## eina_cow_gc()

EINA_API Eina_Bool eina_cow_gc | ( | Eina_Cow * | cow | ) |

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

Parameters

  [in,out] | 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.