Binary Share
Eina » Data Types

This group discusses the functions that allow you to store one copy of an object, and use it throughout your program. More...

## Macros

#define | eina_binshare_add(ptr)
| Retrieves an instance of a blob for use in a program.

## Functions

EINA_API const void * | eina_binshare_add_length (const void *obj, unsigned int olen)
| Retrieves an instance of an object for use in a program.
EINA_API const void * | eina_binshare_ref (const void *obj)
| Increments references of the given shared object.
EINA_API void | eina_binshare_del (const void *obj)
| Notes that the given object has lost an instance.
EINA_API int | eina_binshare_length (const void *obj)
| Notes that the given object must be shared.
EINA_API void | eina_binshare_dump (void)
| Dumps the contents of share_common.

## Detailed Description

This group discusses the functions that allow you to store one copy of an object, and use it throughout your program.

This is a method to reduce the number of duplicated objects kept in the memory.

For more information, you can look at the Binary Share Tutorial.

## Macro Definition Documentation

## eina_binshare_add

#define eina_binshare_add | ( |  | ptr | ) |

Value:
eina_binshare_add_length(ptr, sizeof(*ptr))
eina_binshare_add_length
EINA_API const void * eina_binshare_add_length(const void *obj, unsigned int olen)
Retrieves an instance of an object for use in a program.
Definition eina_binshare.c:158

Retrieves an instance of a blob for use in a program.

This macro retrieves an instance of `obj`. If `obj` is `NULL`, then `NULL` is returned. If `obj` is already stored, it is just returned and its reference counter is increased. Otherwise it is added to the blobs to be searched and a duplicated blob of `obj` is returned.

Parameters

  [in] | ptr | The binary blob to retrieve an instance of

Returns
  A pointer to an instance of the string on success, otherwise `NULL` on failure

Note
  This macro essentially calls eina_binshare_add_length with ptr and sizeof(*ptr) as the parameters. It's useful for pointers to structures.

See also
  eina_stringshare_add_length()

## Function Documentation

## eina_binshare_add_length()

EINA_API const void * eina_binshare_add_length | ( | const void * | obj,
|  | unsigned int | olen )

Retrieves an instance of an object for use in a program.

Parameters

  [in] | obj | The binary object to retrieve an instance of
  [in] | olen | The byte size

Returns
  A pointer to an instance of the object on success, otherwise `NULL` on failure

This function retrieves an instance of `obj`. If `obj` is `NULL`, then `NULL` is returned. If `obj` is already stored, it is just returned and its reference counter is increased. Otherwise it is added to the objects to be searched and a duplicated object of `obj` is returned.

Note
  This function does not check the object size, but uses the exact given size. This can be used to share a part of a larger object or subobject.

See also
  eina_binshare_add()

## eina_binshare_ref()

EINA_API const void * eina_binshare_ref | ( | const void * | obj | ) |

Increments references of the given shared object.

Parameters

  [in] | obj | The shared object

Returns
  A pointer to an instance of the object on success, otherwise `NULL` on failure

Note
  This is similar to eina_share_common_add(), but it's faster since it avoids lookups if possible, but on the down side it requires the parameter to be shared before, in other words, it must be the return of a previous eina_binshare_add().
  There is no unref since this is the work of eina_binshare_del().

## eina_binshare_del()

EINA_API void eina_binshare_del | ( | const void * | obj | ) |

Notes that the given object has lost an instance.

Parameters

  [in] | obj | The given object

This function decreases the reference counter associated to `obj` if it exists. If that counter reaches `0`, the memory associated to `obj` is freed. If `obj` is `NULL`, the function returns immediately.

Warning
  If the given pointer is not shared, bad things happen, mostly a segmentation fault.

## eina_binshare_length()

EINA_API int eina_binshare_length | ( | const void * | obj | ) |

Notes that the given object must be shared.

This function is a cheap way to know the length of a shared object.

Parameters

  [in] | obj | The shared object to know the length It is safe to give `NULL`, in which case `-1` is returned

Returns
  The length of the shared object

Warning
  If the given pointer is not shared, bad things happen, mostly a segmentation fault. If in doubt, try strlen().

## eina_binshare_dump()

EINA_API void eina_binshare_dump | ( | void |  | ) |

Dumps the contents of share_common.

This function dumps all the objects from share_common to stdout with a DDD: prefix per line and a memory usage summary.