s2obj.h File Reference

The object base type and auxiliary definitions for all of SafeTypes2. More...

#include "common.h"

Classes
struct	s2ctx_iter
	The struct s2ctx_iter defines publically visible members of the iterator base type structure. More...

Macros
#define	s2obj_base   struct { s2obj_t base; s2obj_t *pobj; intptr_t ctxinfo; }
	Base header for objects.

Typedefs
typedef T	s2obj_t
	the working context for the base object type s2obj_t. In the following prose, s2obj_t will be abbreviated as T.
typedef struct s2ctx_iter	s2iter_t
	The base type of various iterators.
typedef int(*	s2iter_stepfunc_t) (s2iter_t *restrict ctx)
	The iterator stepping function.
typedef void(*	s2iter_final_func_t) (s2iter_t *restrict ctx)
	frees up resources used by the iterator.
typedef s2iter_t *(*	s2func_iter_create_t) (T *restrict ctx)
typedef void(*	s2func_final_t) (T *restrict ctx)
	subroutine type for the finalizer slot.

Functions
T *	s2gc_obj_alloc (s2obj_typeid_t type, size_t sz)
	Allocates memory for an object. Invoked by type implementations.
void	s2gc_obj_dealloc (T *restrict obj)
	Deallocates memory for the object. Invoked by type implementations.
void	s2gc_set_threading (bool enabled)
	enable or disable threading support in garbage collector.
void	s2gc_collect (void)
	Explicitly invoke SafeTypes2 garbage collection. Applications that never creates reference cycles don't need this.
T *	s2obj_retain (T *restrict obj)
	Increases reference count. Invoked by the application.
T *	s2obj_keep (T *restrict obj)
	Increases 'kept' count. Invoked by container implementations.
void	s2obj_release (T *restrict obj)
	Decreases reference count. Invoked by the application.
void	s2obj_leave (T *restrict obj)
	Decreases 'kept' count. Invoked by container implementations.
s2iter_t *	s2obj_iter_create (T *restrict obj)
	creates an iterator by invoking the internal itercreatf.
int	s2gc_thrd_lock ()
	To obtain a "reader" lock for the application thread. ("thrd" is a fortunate portmanteau of "thread-reading".)
int	s2gc_thrd_unlock ()
	To release the "reader" lock from a application thread.

Detailed Description

The object base type and auxiliary definitions for all of SafeTypes2.

Macro Definition Documentation

s2obj_base

#define s2obj_base   struct { s2obj_t base; s2obj_t *pobj; intptr_t ctxinfo; }

Base header for objects.

This is the base object header to be placed at the beginning of all types derived from s2obj_t.

• The pobj field will point to the beginning address of the object, which make it easy to refer to the object itself as an s2obj_t.
• The ctxinfo can hold contextual information for arbitrary purpose.

Typedef Documentation

s2func_final_t

typedef void(* s2func_final_t) (T *restrict ctx)

subroutine type for the finalizer slot.

Parameters

ctx	the handle pointer to the object to finalize.

When both the reference and the kept count of an object is zero, its finalization routine is invoked and object is freed.

s2func_iter_create_t

typedef s2iter_t *(* s2func_iter_create_t) (T *restrict ctx)

Returns

non-NULL on success and NULL on failure.

Note

This is a change from the original SafeTypes library - instead of keeping iterator state on the object, separate iterator context is used so that 1 (read-only) object may have different iterator positions.

s2iter_final_func_t

typedef void(* s2iter_final_func_t) (s2iter_t *restrict ctx)

frees up resources used by the iterator.

Parameters

ctx	the pointer handle to the iterator

s2iter_stepfunc_t

typedef int(* s2iter_stepfunc_t) (s2iter_t *restrict ctx)

The iterator stepping function.

Parameters

ctx	the pointer handle to the iterator.

Returns

1 on success, 0 at the end, and -1 on error.

Iterator creator functions doen't set the position, a initial call to step function is needed to initialize the position of the iterator.

Function Documentation

s2gc_collect()

void s2gc_collect

(

void

)

Explicitly invoke SafeTypes2 garbage collection. Applications that never creates reference cycles don't need this.

Note

2025-02-15: This function is not available in a build without GC.

s2gc_obj_alloc()

T * s2gc_obj_alloc	(	s2obj_typeid_t	type,
		size_t	sz )

Allocates memory for an object. Invoked by type implementations.

Parameters

type	the type id for the object, see Type Identifier Name Space.

Returns

the pointer handle to the object.

s2gc_obj_dealloc()

void s2gc_obj_dealloc

(

T *restrict

obj

)

Deallocates memory for the object. Invoked by type implementations.

Parameters

obj	the object to deallocate.

additional resources are released by finalizer.

s2gc_set_threading()

void s2gc_set_threading

(

bool

enabled

)

enable or disable threading support in garbage collector.

Parameters

enabled

true to enable threading, and false to disable it.

2024-03-09: It is assumed that this will only be called when there's only 1 thread. By default, threading is enabled for GC, and this function is provided for single-threaded applications to avoid synchronization overheads.

s2gc_thrd_lock()

int s2gc_thrd_lock

(

)

To obtain a "reader" lock for the application thread. ("thrd" is a fortunate portmanteau of "thread-reading".)

Note

2025-02-15: This function is not available in a build without GC.

s2gc_thrd_unlock()

int s2gc_thrd_unlock

(

)

To release the "reader" lock from a application thread.

Note

2025-02-15: This function is not available in a build without GC.

s2obj_iter_create()

s2iter_t * s2obj_iter_create

(

T *restrict

obj

)

creates an iterator by invoking the internal itercreatf.

Parameters

obj	the object of which the iterator is created.

Returns

the iterator object, or NULL on failure.

s2obj_keep()

T * s2obj_keep

(

T *restrict

obj

)

Increases 'kept' count. Invoked by container implementations.

Returns

obj

Note

2025-02-15: This function is identical to s2obj_retain in builds without GC.

s2obj_leave()

void s2obj_leave

(

T *restrict

obj

)

Decreases 'kept' count. Invoked by container implementations.

Note

2025-02-15: This function is identical to s2obj_release in builds without GC.

s2obj_retain()

T * s2obj_retain

(

T *restrict

obj

)

Increases reference count. Invoked by the application.

Returns

obj