sc_refcount.h File Reference

Provide reference counting facilities. More...

#include <sc.h>

Include dependency graph for sc_refcount.h:

Go to the source code of this file.

Data Structures
struct	sc_refcount
	The refcount structure is declared in public so its size is known. More...

Typedefs
typedef struct sc_refcount	sc_refcount_t
	The refcount structure is declared in public so its size is known. More...

Functions
void	sc_refcount_init_invalid (sc_refcount_t *rc)
	Initialize a well-defined but unusable reference counter. More...
void	sc_refcount_init (sc_refcount_t *rc, int package_id)
	Initialize a reference counter to 1. More...
sc_refcount_t *	sc_refcount_new (int package_id)
	Create a new reference counter with count initialized to 1. More...
void	sc_refcount_destroy (sc_refcount_t *rc)
	Destroy a reference counter. More...
void	sc_refcount_ref (sc_refcount_t *rc)
	Increase a reference counter. More...
int	sc_refcount_unref (sc_refcount_t *rc)
	Decrease the reference counter and notify when it reaches zero. More...
int	sc_refcount_is_active (const sc_refcount_t *rc)
	Check whether a reference counter has a positive value. More...
int	sc_refcount_is_last (const sc_refcount_t *rc)
	Check whether a reference counter has value one. More...

Detailed Description

Provide reference counting facilities.

The functions in this file can be used for multiple purposes. The current setup is not so much targeted at garbage collection but rather intended for debugging and verification.

Typedef Documentation

sc_refcount_t

typedef struct sc_refcount sc_refcount_t

The refcount structure is declared in public so its size is known.

Its members should really never be accessed directly.

Function Documentation

sc_refcount_destroy()

void sc_refcount_destroy

(

sc_refcount_t *

rc

)

Destroy a reference counter.

It must have been counted down to zero before, thus reached an inactive state.

Parameters

[in,out]

rc

This reference counter must have reached count zero.

sc_refcount_init()

void sc_refcount_init	(	sc_refcount_t *	rc,
		int	package_id
	)

Initialize a reference counter to 1.

It is legal if its status prior to this call is undefined.

Parameters

[out]	rc	This reference counter is initialized to one. The object's contents may be undefined on input.
[in]	package_id	Either -1 or a package registered to libsc.

sc_refcount_init_invalid()

void sc_refcount_init_invalid

(

sc_refcount_t *

rc

)

Initialize a well-defined but unusable reference counter.

Specifically, we set its package identifier and reference count to -1. To make this reference counter usable, call sc_refcount_init.

Parameters

[out]

rc

This reference counter is defined as invalid. It will return false on both sc_refcount_is_active and sc_refcount_is_last. It can be made valid by calling sc_refcount_init. No other functions must be called on it.

sc_refcount_is_active()

int sc_refcount_is_active

(

const sc_refcount_t *

rc

)

Check whether a reference counter has a positive value.

This means that the reference counter is in use and corresponds to a live object.

Parameters

[in]

rc

A reference counter.

Returns

True if the count is greater zero, false otherwise.

sc_refcount_is_last()

int sc_refcount_is_last

(

const sc_refcount_t *

rc

)

Check whether a reference counter has value one.

This means that this counter is the last of its kind, which we may optimize for.

Parameters

[in]

rc

A reference counter.

Returns

True if the count is exactly one.

sc_refcount_new()

sc_refcount_t* sc_refcount_new

(

int

package_id

)

Create a new reference counter with count initialized to 1.

Equivalent to calling sc_refcount_init on a newly allocated rc object.

Parameters

[in]

package_id

Either -1 or a package registered to libsc.

Returns

A reference counter with count one.

sc_refcount_ref()

void sc_refcount_ref

(

sc_refcount_t *

rc

)

Increase a reference counter.

The counter must be active, that is, have a value greater than zero.

Parameters

[in,out]

rc

This reference counter must be valid (greater zero). Its count is increased by one.

sc_refcount_unref()

int sc_refcount_unref

(

sc_refcount_t *

rc

)

Decrease the reference counter and notify when it reaches zero.

The count must be greater zero on input. If the reference count reaches zero, which is indicated by the return value, the counter may not be used further with sc_refcount_ref or

See also

sc_refcount_unref. It is legal, however, to reactivate it later by calling

sc_refcount_init.

Parameters

[in,out]

rc

This reference counter must be valid (greater zero). Its count is decreased by one.

Returns

True if the count has reached zero, false otherwise.