Tizen Native API  5.5
Copy On Write

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 (EFL) :
1.8.0

Functions

Eina_Coweina_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.
void eina_cow_del (Eina_Cow *cow)
 Destroys an Eina_Cow pool and all the allocated memory.
const Eina_Cow_Dataeina_cow_alloc (Eina_Cow *cow)
 Returns an initialized pointer from the pool.
void eina_cow_free (Eina_Cow *cow, const Eina_Cow_Data **data)
 Frees a pointer from the pool.
void * eina_cow_write (Eina_Cow *cow, const Eina_Cow_Data *const *src)
 Gets a writeable pointer from a const pointer.
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.
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_Bool eina_cow_gc (Eina_Cow *cow)
 Tries to find entries that have the same content and update them.

Typedefs

typedef struct _Eina_Cow Eina_Cow
typedef void Eina_Cow_Data

Defines

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

Define 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:
[in,out]CowThe Eina_Cow where the const pointer came from.
[in]ReadThe const pointer to get a writable handler from.
[in]Write_TypeThe type of the pointer you want to write to.
[in]WriteThe name of the variable where to put the writeable pointer to.
Since (EFL) :
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:
[in,out]CowThe Eina_Cow where the const pointer came from.
[in]ReadThe const pointer to get a writable handler from.
[in]WriteThe name of the variable where to put the writeable pointer to.
Since (EFL) :
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:
[in,out]CowThe Eina_Cow where the const pointer came from.
[in]ReadThe const pointer to get a writable handler from.
[in]WriteThe name of the variable where to put the writeable pointer to.
Since (EFL) :
1.8.0
Note:
This macro closes the scope opened by EINA_COW_WRITE_BEGIN().

Typedef Documentation

Type for Eina_Cow pool

Type of the returned pointer to simplify some reading.


Function Documentation

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]nameThe name of this pool, used for debugging.
[in]struct_sizeThe size of the object from this pool.
[in]stepHow many objects to allocate when the pool gets empty.
[in]default_valueThe default value returned by this pool.
[in]gcIs it possible to run garbage collection on this pool.
Returns:
A valid new Eina_Cow, or NULL on error.
Since :
3.0

Returns an initialized pointer from the pool.

Parameters:
[in]cowThe pool to take things from.
Returns:
A pointer to the new pool instance
Since :
3.0f(2.3.1)
void eina_cow_del ( Eina_Cow cow)

Destroys an Eina_Cow pool and all the allocated memory.

Parameters:
[in]cowThe pool to destroy
Since :
3.0f(2.3.1)
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]cowThe pool the pointer came from.
[in]dstThe read only version of the pointer.
[in]dataThe pointer to which data was written to.
[in]needed_gcDoes this pool need to be garbage collected?
Note:
This function is not thread safe.
Since :
3.0f(2.3.1)
void eina_cow_free ( Eina_Cow cow,
const Eina_Cow_Data **  data 
)

Frees a pointer from the pool.

Parameters:
[in,out]cowThe pool to gave back memory to.
[in]dataThe 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.
Since :
3.0f(2.3.1)

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

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

Since :
3.0f(2.3.1)
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]cowThe pool the pointers came from.
[in]dstThe destination to update.
[in]srcThe source of information to copy.
Since :
3.0f(2.3.1)
void* eina_cow_write ( Eina_Cow cow,
const Eina_Cow_Data *const *  src 
)

Gets a writeable pointer from a const pointer.

Parameters:
[in,out]cowThe pool the pointer came from.
[in]srcThe pointer you want to write to.
Note:
This function is not thread safe.
Since :
3.0f(2.3.1)