Space Observer Interface

Functions for implementing a Space Observer to monitor changes to a Space from C. More...

Classes
struct	space_event_t
	Represents a Space Event. More...
struct	space_observer_t
	Represents a Space Observer, registered with a Space. More...
struct	space_observer_api_t
	A table of callback functions to define the behavior of a SpaceObserver implemented in C. More...

Enumerations
enum	space_event_type_t { SPACE_EVENT_TYPE_ADD , SPACE_EVENT_TYPE_REMOVE , SPACE_EVENT_TYPE_REPLACE }
	Represents different types of Space Events. More...
enum	space_event_field_t { SPACE_EVENT_FIELD_ADD , SPACE_EVENT_FIELD_REMOVE , SPACE_EVENT_FIELD_REPLACE_PATTERN , SPACE_EVENT_FIELD_REPLACE_TEMPLATE }
	Accessor constants, to access the fields of a space_event_t More...

Functions
enum space_event_type_t	space_event_get_type (const struct space_event_t *event)
	Gets the type of a Space Event.
atom_ref_t	space_event_get_field_atom (const struct space_event_t *event, enum space_event_field_t field)
	Accesses the atom associated with a field of a space_event_t
struct space_observer_t	space_register_observer (struct space_t *space, const struct space_observer_api_t *observer_api, void *observer_payload)
	Registers a new observer, to monitor activity within the Space.
void	space_observer_free (struct space_observer_t observer)
	Frees a space_observer_t
void *	space_observer_get_payload (const struct space_observer_t *observer)
	Returns a pointer to the payload associated with the space_observer_t.

Detailed Description

Functions for implementing a Space Observer to monitor changes to a Space from C.

Space Observers permit code to monitor activity within a Space by receiving events. Additionally, custom Space implementations must notify all observers by broadcasting events to communicate activity within the space.

Enumeration Type Documentation

space_event_field_t

enum space_event_field_t

Accessor constants, to access the fields of a space_event_t

Enumerator
SPACE_EVENT_FIELD_ADD	Access the atom field of an Add event.
SPACE_EVENT_FIELD_REMOVE	Access the atom field of a Remove event.
SPACE_EVENT_FIELD_REPLACE_PATTERN	Access the pattern field of a Replace event.
SPACE_EVENT_FIELD_REPLACE_TEMPLATE	Access the template field of a Replace event.

space_event_type_t

enum space_event_type_t

Represents different types of Space Events.

Enumerator
SPACE_EVENT_TYPE_ADD	The event is an Add event.
SPACE_EVENT_TYPE_REMOVE	The event is a Remove event.
SPACE_EVENT_TYPE_REPLACE	The event is a Replace event.

Function Documentation

space_event_get_field_atom()

atom_ref_t space_event_get_field_atom	(	const struct space_event_t *	event,
		enum space_event_field_t	field )

Accesses the atom associated with a field of a space_event_t

Parameters

[in]	event	A pointer to the event to access
[in]	field	A space_event_field_t specifying which field to access

Returns

An atom_ref_t referencing the specified atom within the event

Warning

The returned atom_ref_t is borrowed from the space_event_t, and it must not be modified or accessed after the event has been freed

space_event_get_type()

enum space_event_type_t space_event_get_type

(

const struct space_event_t *

event

)

Gets the type of a Space Event.

Parameters

[in]

event

A pointer to the event to inspect

Returns

The type of the event

space_observer_free()

void space_observer_free

(

struct space_observer_t

observer

)

Frees a space_observer_t

Parameters

[in]

observer

The space_observer_t to free

Note

Freeing a Space Observer will atomatically de-register it with its associated space

space_observer_get_payload()

void * space_observer_get_payload

(

const struct space_observer_t *

observer

)

Returns a pointer to the payload associated with the space_observer_t.

Parameters

[in]

observer

A pointer to the space_observer_t in which to access the payload

Returns

A pointer to the payload object associated with the Space Observer

Warning

The returned pointer must not be accessed after the space_observer_t has been freed, or after any operations have occurred that may have caused events to occur in the associated space

The returned pointer should never be freed directly. Call space_observer_free() when you are finished with the observer

space_register_observer()

struct space_observer_t space_register_observer	(	struct space_t *	space,
		const struct space_observer_api_t *	observer_api,
		void *	observer_payload )

Registers a new observer, to monitor activity within the Space.

Parameters

[in]	space	A pointer to the space_t handle of the space to observe
[in]	observer_api	A pointer to the table of functions that implement the observer's behavior
[in]	observer_payload	A pointer to a caller-defined object usable by the observer's implementation functions

Returns

A space_observer_t created to observe the space

Note

The caller must take ownership responsibility for the returned space_observer_t, and it must be freed with space_observer_free()

Warning

This function takes ownership of the observer_payload, and it should not be freed after it has been provided to this function