Reference Counting

Couchbase Lite "objects" are reference-counted; the functions below are the shared retain and release operations. More...

Macros
#define	CBL_REFCOUNTED(TYPE, NAME)

Typedefs
typedef struct CBLRefCounted	CBLRefCounted

Functions
CBLRefCounted *	CBL_Retain (CBLRefCounted *_cbl_nullable)
	Increments an object's reference-count. More...
void	CBL_Release (CBLRefCounted *_cbl_nullable)
	Decrements an object's reference-count, freeing the object if the count hits zero. More...
unsigned	CBL_InstanceCount (void)
	Returns the total number of Couchbase Lite objects. More...
void	CBL_DumpInstances (void)
	Logs the class and address of each Couchbase Lite object. More...

Detailed Description

Couchbase Lite "objects" are reference-counted; the functions below are the shared retain and release operations.

(But there are type-safe equivalents defined for each class, so you can call CBLDatabase_Release() on a database, for instance, without having to type-cast.)

API functions that create a ref-counted object (typically named ..._New() or ..._Create()) return the object with a ref-count of 1; you are responsible for releasing the reference when you're done with it, or the object will be leaked.

Other functions that return an existing ref-counted object do not modify its ref-count. You do not need to release such a reference. But if you're keeping a reference to the object for a while, you should retain the reference to ensure it stays alive, and then release it when finished (to balance the retain.)

Macro Definition Documentation

CBL_REFCOUNTED

#define CBL_REFCOUNTED	(		TYPE,
			NAME
	)

Value:

    static inline const TYPE CBL##NAME##_Retain(const TYPE _cbl_nullable t) \
                                            {return (const TYPE)CBL_Retain((CBLRefCounted*)t);} \
    static inline void CBL##NAME##_Release(const TYPE _cbl_nullable t) {CBL_Release((CBLRefCounted*)t);}

Typedef Documentation

CBLRefCounted

typedef struct CBLRefCounted CBLRefCounted

Function Documentation

CBL_DumpInstances()

void CBL_DumpInstances

(

void

)

Logs the class and address of each Couchbase Lite object.

Useful for leak checking.

Note

May only be functional in debug builds of Couchbase Lite.

CBL_InstanceCount()

unsigned CBL_InstanceCount

(

void

)

Returns the total number of Couchbase Lite objects.

Useful for leak checking.

CBL_Release()

void CBL_Release

(

CBLRefCounted *

_cbl_nullable

)

Decrements an object's reference-count, freeing the object if the count hits zero.

Usually you'll call one of the type-safe synonyms specific to the object type, like CBLDatabase_Release.

CBL_Retain()

CBLRefCounted * CBL_Retain

(

CBLRefCounted *

_cbl_nullable

)

Increments an object's reference-count.

Usually you'll call one of the type-safe synonyms specific to the object type, like CBLDatabase_Retain`