Copy On Write

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. More...
#define	EINA_COW_WRITE_END(Cow, Read, Write)
	Definition for the macro to close the writeable pointer. More...
#define	EINA_COW_WRITE_END_NOGC(Cow, Read, Write)
	Definition for the macro to close the writeable pointer without triggering the GC. More...

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

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)));

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().

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]	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().

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);

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

eina_cow_del()

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 evas_shutdown().

eina_cow_alloc()

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()

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, EINA_MAGIC_SET, and eina_mempool_free().

Referenced by eina_cow_memcpy().

eina_cow_write()

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, eina_mempool_malloc(), and ERR.

eina_cow_done()

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()

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