Reference counter

Handle automatic cleanup of user's data. More...

Collaboration diagram for Reference counter:

Data Structures
struct	discord_refcounter
	Automatically cleanup user data. More...

Functions
void	discord_refcounter_init (struct discord_refcounter *rc, struct logconf *conf)
	Initialize reference counter handle. More...
void	discord_refcounter_add_internal (struct discord_refcounter *rc, void *data, void(*cleanup)(void *data), bool should_free)
	Add a new internal reference to the reference counter. More...
void	discord_refcounter_add_client (struct discord_refcounter *rc, void *data, void(*cleanup)(struct discord *client, void *data), bool should_free)
	Add a new client reference to the reference counter. More...
void	discord_refcounter_cleanup (struct discord_refcounter *rc)
	Cleanup refcounter and all user data currently held. More...
CCORDcode	discord_refcounter_claim (struct discord_refcounter *rc, const void *data)
	Claim ownership of data More...
CCORDcode	discord_refcounter_unclaim (struct discord_refcounter *rc, void *data)
	Unclaim ownership of data More...
CCORDcode	discord_refcounter_incr (struct discord_refcounter *rc, void *data)
	Increment the reference counter for ret->data More...
CCORDcode	discord_refcounter_decr (struct discord_refcounter *rc, void *data)
	Decrement the reference counter for data More...

Detailed Description

Handle automatic cleanup of user's data.

Function Documentation

discord_refcounter_init()

void discord_refcounter_init	(	struct discord_refcounter *	rc,
		struct logconf *	conf
	)

Initialize reference counter handle.

A hashtable shall be used for storage and retrieval of user data

Parameters

rc	the reference counter handle to be initialized
conf	pointer to discord logging module

discord_refcounter_add_internal()

void discord_refcounter_add_internal	(	struct discord_refcounter *	rc,
		void *	data,
		void(*)(void *data)	cleanup,
		bool	should_free
	)

Add a new internal reference to the reference counter.

Parameters

rc	the handle initialized with discord_refcounter_init()
data	the data address to be referenced
cleanup	function for cleaning data resources once its no longer referenced
should_free	whether data cleanup should be followed by a free()

discord_refcounter_add_client()

void discord_refcounter_add_client	(	struct discord_refcounter *	rc,
		void *	data,
		void(*)(struct discord *client, void *data)	cleanup,
		bool	should_free
	)

Add a new client reference to the reference counter.

Parameters

rc	the handle initialized with discord_refcounter_init()
data	the data address to be referenced
cleanup	function for cleaning data resources once its no longer referenced
should_free	whether data cleanup should be followed by a free()

discord_refcounter_cleanup()

void discord_refcounter_cleanup

(

struct discord_refcounter *

rc

)

Cleanup refcounter and all user data currently held.

Parameters

rc	the handle initialized with discord_refcounter_init()

discord_refcounter_claim()

CCORDcode discord_refcounter_claim	(	struct discord_refcounter *	rc,
		const void *	data
	)

Claim ownership of data

See also

discord_refcounter_unclaim()

After ownership is claimed data will no longer be cleaned automatically, instead shall be cleaned only when the same amount of discord_refcounter_unclaim() have been called

Parameters

rc	the handle initialized with discord_refcounter_init()
data	the data to have its ownership claimed

Return values

CCORD_OK	counter for data has been incremented
CCORD_RESOURCE_UNAVAILABLE	couldn't find a match to data

discord_refcounter_unclaim()

CCORDcode discord_refcounter_unclaim	(	struct discord_refcounter *	rc,
		void *	data
	)

Unclaim ownership of data

See also

discord_refcounter_claim()

This will make the resource eligible for cleanup, so this should only be called when you no longer plan to use it

Parameters

rc	the handle initialized with discord_refcounter_init()
data	the data to have its ownership unclaimed

Return values

CCORD_OK	counter for data has been decremented
CCORD_RESOURCE_UNAVAILABLE	couldn't find a match to data
CCORD_RESOURCE_OWNERSHIP	data has never been discord_claim() 'd

discord_refcounter_incr()

CCORDcode discord_refcounter_incr	(	struct discord_refcounter *	rc,
		void *	data
	)

Increment the reference counter for ret->data

See also

discord_refcounter_decr()

Parameters

rc	the handle initialized with discord_refcounter_init()
data	the data to have its reference counter incremented

Return values

CCORD_OK	counter for data has been incremented
CCORD_RESOURCE_UNAVAILABLE	couldn't find a match to data

discord_refcounter_decr()

CCORDcode discord_refcounter_decr	(	struct discord_refcounter *	rc,
		void *	data
	)

Decrement the reference counter for data

See also

discord_refcounter_incr()

If the count reaches zero then data shall be cleanup up with its user-defined cleanup function

Parameters

rc	the handle initialized with discord_refcounter_init()
data	the data to have its reference counter decremented

Return values

CCORD_OK	counter for data has been decremented
CCORD_RESOURCE_UNAVAILABLE	couldn't find a match to data
CCORD_RESOURCE_OWNERSHIP	caught attempt to cleanup a claimed resource