Safe Pointer

These functions provide a wrapper that protect access to pointers. More...

Typedefs
typedef struct _Eina_Safepointer	Eina_Safepointer
	Type of the protected index.

Functions
EINA_API const Eina_Safepointer *	eina_safepointer_register (const void *target)
	Register a pointer and get an Eina_Safepointer that maps to it. More...
EINA_API void	eina_safepointer_unregister (const Eina_Safepointer *safe)
	Unregister an Eina_Safepointer and the pointer that maps to it. More...
static void *	eina_safepointer_get (const Eina_Safepointer *safe)
	Get the associated pointer from an Eina_Safepointer mapping. More...

Detailed Description

These functions provide a wrapper that protect access to pointers.

Eina_Safepointer is an pointer to index converter that allows an increased level of safety by forbidding direct access to the pointer. The protection works by using a set of indirection tables that are mmapped and mprotected against write access. Thus the pointer they store and that map to a specific index is always correct. Also once a pointer is unregistered the index won't be served back for 2^8 on 32 bits system and 2^28 on 64 bits system for that specific slot. Finally we guarantee that the lower 2 bits of the returned index are actually never used and completely ignored by our API. So you can safely store whatever information you want in it, we will ignore it and treat as if it wasn't there.

Note

The use of Eina_Safepointer is thread safe.

Function Documentation

eina_safepointer_register()

EINA_API const Eina_Safepointer * eina_safepointer_register

(

const void *

target

)

Register a pointer and get an Eina_Safepointer that maps to it.

Parameters

[in]

target

The pointer to register.

Returns

A valid pointer that is an index to the mapped pointer.

Note

It will return NULL on error or if target is NULL.

The lower 2 bits of the returned pointer will always be 0.

The returned pointer can be used like a pointer, but cannot be touched except with Eina_Safepointer functions.

Since

1.18

References eina_spinlock_release(), and eina_spinlock_take().

eina_safepointer_unregister()

EINA_API void eina_safepointer_unregister

(

const Eina_Safepointer *

safe

)

Unregister an Eina_Safepointer and the pointer that maps to it.

Parameters

[in]

safe

The index to unregister from the mapping.

Note

This function will ignore the lower 2 bits of the given pointer.

Since

1.18

References eina_spinlock_release(), eina_spinlock_take(), and eina_trash_push().

eina_safepointer_get()

static void * eina_safepointer_get ( const Eina_Safepointer *  safe )

inlinestatic

Get the associated pointer from an Eina_Safepointer mapping.

Parameters

[in]

safe

The Eina_Safepointer index to lookup at.

Returns

The pointer registered with that index or NULL in any other case.

Note

It is always safe to ask for a pointer for any value of the mapping. If the pointer is invalid or NULL, we will return NULL and not crash.