s2ref.h File Reference

The 'reference' type (container of a single externally-managed pointer). More...

#include "s2obj.h"

Macros
#define	s2_is_ref(obj)

Typedefs
typedef T	s2ref_t
	the working context for the 'reference' type s2ref_t. In the following prose, s2ref_t will be abbreviated as T.
typedef void(*	s2ref_final_func_t) (void *ptr)
	the pointer to function that finalizes ptr.

Functions
T *	s2ref_create (void *ptr, s2ref_final_func_t finalizer)
	Creates and returns an reference object.
T *	s2ref_create_weakref (void *ptr)
	Creates a weak reference. Equivalent to s2ref_create(ptr, NULL).
void *	s2ref_unwrap (T *ref)
	retrieve the underlying pointer.

Detailed Description

The 'reference' type (container of a single externally-managed pointer).

The purpose of this type is 2-fold:

1. it allows arbitrary user resource from the application or 3rd-party libraries to be managed under SafeTypes2.
2. it enables the program to (either entirely, or in compartments) opt out of tracing garbage collection and use weakrefs instead.

Macro Definition Documentation

s2_is_ref

#define s2_is_ref

(

obj

)

Value:

(((s2obj_t *)obj)->type == S2_OBJ_TYPE_REF)

Parameters

obj	the object handle the type of which is being checked.

Returns

true if the object is a 'reference', false otherwise.

Function Documentation

s2ref_create()

T * s2ref_create	(	void *	ptr,
		s2ref_final_func_t	finalizer )

Creates and returns an reference object.

Parameters

ptr	the pointer to wrap in the reference object.
finalizer	finalizes the underlying pointer.

Returns

a pointer to the list object handle, or NULL on error.

Note

The behavior of finalizer were ill-defined in versions before 2025-02-19. From the 2025-02-19 revision onwards, the finalizer (if provided) will be called with the value of ptr - this way, the finalizers can be used in their existing form, without having to wrap them in subroutines that does nothing other than to retrieves ptr from the context structure,

s2ref_unwrap()

void * s2ref_unwrap

(

T *

ref

)

retrieve the underlying pointer.

Returns

the underlying pointer.