Refcounting

RRef is the refcount base struct that every refcounted type in rlib embeds at offset 0 - hashtables, buffers, crypto handles, RTC sessions, parsers, the rest. More...

Files
file	rref.h
	Refcount base struct shared by every refcounted type in rlib.

Data Structures
struct	RRef
	Refcount base struct. More...

Macros
#define	r_ref_refcount(ref)   r_atomic_uint_load (&((RRef *)ref)->refcount)
	Snapshot of the current refcount (atomic load).
#define	R_REF_STATIC_INIT(destroy)   { 0, 0, (RDestroyNotify)destroy }
	Static initialiser for an embedded RRef field.
#define	r_ref_init(self, destroy)
	Initialise an RRef field to refcount 1 with destructor destroy.

Functions
rpointer	r_ref_ref (rpointer ref)
	Increment the refcount and return the same pointer.
void	r_ref_unref (rpointer ref)
	Decrement the refcount; runs the destructor when it reaches zero.
rpointer	r_ref_weak_ref (rpointer ref, RFunc notify, rpointer data)
	Register a weak-reference callback that fires when ref is destroyed.
rboolean	r_ref_weak_unref (rpointer ref, RFunc notify, rpointer data)
	Cancel a previously registered weak-reference callback.

Detailed Description

RRef is the refcount base struct that every refcounted type in rlib embeds at offset 0 - hashtables, buffers, crypto handles, RTC sessions, parsers, the rest.

Concrete types derive from RRef by placing it as the first field of their own struct and supplying a destroy notifier at construction. The r_ref_ref / r_ref_unref pair drives the lifecycle; r_ref_weak_ref / r_ref_weak_unref register weak-reference callbacks fired when the refcount drops to zero.

Macro Definition Documentation

r_ref_init

#define r_ref_init	(		self,
			destroy
	)

Value:

  R_STMT_START {                      \
  r_atomic_uint_store (&((RRef *)self)->refcount, 1);                         \
  r_atomic_ptr_store (&((RRef *)self)->weaklst, NULL);                        \
  ((RRef *)self)->notify = (RDestroyNotify)destroy;                           \
} R_STMT_END

Initialise an RRef field to refcount 1 with destructor destroy.

R_REF_STATIC_INIT

#define R_REF_STATIC_INIT

(

destroy

)

{ 0, 0, (RDestroyNotify)destroy }

Static initialiser for an embedded RRef field.

The refcount starts at 0 so the embedder can call r_ref_ref before the first external reference is handed out; alternatively use r_ref_init at runtime.

Function Documentation

r_ref_weak_ref()

rpointer r_ref_weak_ref	(	rpointer	ref,
		RFunc	notify,
		rpointer	data
	)

Register a weak-reference callback that fires when ref is destroyed.

Parameters

ref	The refcounted object.
notify	Function to invoke when ref's refcount reaches zero.
data	Cookie passed to notify.