- Main Page
- Related Pages
- Modules
- Data Structures
- Files
- Examples

Macros | Functions
Binary Share
Data Types

These functions allow you to store one copy of an object, and use it throughout your program. More...

## Macros
#define | eina_binshare_add(ptr) eina_binshare_add_length(ptr, sizeof(*ptr))
| Retrieve an instance of a blob for use in a program. More...

## Functions
EAPI const void * | eina_binshare_add_length (const void *obj, unsigned int olen) EINA_WARN_UNUSED_RESULT
| Retrieve an instance of an object for use in a program. More...
EAPI const void * | eina_binshare_ref (const void *obj)
| Increment references of the given shared object. More...
EAPI void | eina_binshare_del (const void *obj)
| Note that the given object has lost an instance. More...
EAPI int | eina_binshare_length (const void *obj) EINA_WARN_UNUSED_RESULT EINA_PURE
| Note that the given object must be shared. More...
EAPI void | eina_binshare_dump (void)
| Dump the contents of the share_common. More...

## Detailed Description

These functions 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 memory.

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

## Macro Definition Documentation

#define eina_binshare_add | ( |  | ptr | ) | eina_binshare_add_length(ptr, sizeof(*ptr))

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

Parameters

  ptr | The binary blob to retrieve an instance of.

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

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.

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

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

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

Parameters

  obj | The binary object to retrieve an instance of.
  olen | The byte size

Returns
  A pointer to an instance of the object on success. `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.

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

See Also
  eina_binshare_add()

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

Increment references of the given shared object.

Parameters

  obj | The shared object.

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

This is similar to eina_share_common_add(), but it's faster since it will avoid 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().

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

Note that the given object has lost an instance.

Parameters

  obj | object 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.

Note
  If the given pointer is not shared, bad things will happen, likely a segmentation fault.

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

Note that the given object must be shared.

Parameters

  obj | the shared object to know the length. It is safe to give `NULL`, in that case `-1` is returned.

Returns
  The length of the shared object.

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

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

EAPI void eina_binshare_dump | ( | void |  | ) |

Dump the contents of the share_common.

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