state.h File Reference

A state notification mechanism. More...

#include <sys/stat.h>

Go to the source code of this file.

Functions
int	state_init (int abi_version, int flags)
	Initialize the state notification mechanism. More...
void	state_atexit (void)
	Free all resources used by the state notification mechanism. More...
int	state_bind (const char *name)
	Acquire the ability to publish notifications about a name More...
int	state_unbind (const char *name)
	Stop publishing information about <name> More...
int	state_subscribe (const char *name)
	Subscribe to notifications about a name. More...
int	state_unsubscribe (const char *name)
	Stop subscribing to notifications about <name> More...
int	state_publish (const char *name, const char *state, size_t len)
	Publish a notification about name and update the state. More...
ssize_t	state_check (char **key, char **value)
	Check for pending notifications, and return the current state. More...
int	state_get (const char *key, char **value)
	Get the current state of a <name>. More...
int	state_get_event_fd (void)
	Get a file descriptor that can be monitored for readability. More...
int	state_openlog (const char *logfile)
	Submit a block to be executed when one or more state change notifications are pending. More...
int	state_closelog (void)
	Close the logfile. More...

Detailed Description

A state notification mechanism.

Function Documentation

void state_atexit

(

void

)

Free all resources used by the state notification mechanism.

This is intended to be registered with atexit(3) to run when the program exits.

int state_bind

(

const char *

name

)

Acquire the ability to publish notifications about a name

Parameters

name	the name to acquire

Returns

0 if successful, or -1 if an error occurs.

Examples:

publisher.dox.

ssize_t state_check	(	char **	key,
		char **	value
	)

Check for pending notifications, and return the current state.

Parameters

key	Will be filled in with the published name
value	The current value of the state

Returns

the length of the value string, or, 0 if no new notifications were available, or -1 if an error occurs.

Examples:

subscriber.dox.

int state_closelog

(

void

)

Close the logfile.

Returns

0 if successful, or -1 if an error occurs.

int state_get	(	const char *	key,
		char **	value
	)

Get the current state of a <name>.

Parameters

name	the name of the notification
value	a string that will be modified to point at the current state

Returns

the length of the

string, or -1 if an error occurred

Examples:

subscriber.dox.

int state_get_event_fd

(

void

)

Get a file descriptor that can be monitored for readability.

When one more notifications are pending, the file descriptor will become ready for reading. This descriptor can be added to your application's event loop.

This descriptor could be used with libdispatch by following this example:

dispatch_source_t source = dispatch_source_create( DISPATCH_SOURCE_TYPE_READ, state_get_event_fd(), 0, dispatch_get_main_queue()); dispatch_source_set_event_handler(source, ^{ char *name, *state; ssize_t len;

len = state_check(&name, &state); if (len > 0) { printf("state update: %s is now %s\n", name, state); } }); dispatch_resume(source);

Returns

a file descriptor, or -1 if an error occurred.

Examples:

subscriber.dox.

int state_init	(	int	abi_version,
		int	flags
	)

Initialize the state notification mechanism.

Parameters

ABI_version	The ABI version number for compatibility. This should be set to zero.
flags	Reserved for future use. This should be set to zero.

Returns

0 if successful, or -1 if an error occurs.

Examples:

publisher.dox, and subscriber.dox.

int state_openlog

(

const char *

logfile

)

Submit a block to be executed when one or more state change notifications are pending.

This is basically a convenience function that implements the example code shown in the documentation for notify_get_fd().

You must include <dispatch/dispatch.h> and compile with -fblocks to have access to this function.

Parameters

name	the name of the notification to wait for
queue	the dispatch queue to run the block on
block	the block of code to be executed Execute a callback function when one or more notifications are pending.

This is equivalent to state_dispatch(), but without using blocks. Open a logfile.

Parameters

logfile

the path to the logfile

Returns

0 if successful, or -1 if an error occurs.

int state_publish	(	const char *	name,
		const char *	state,
		size_t	len
	)

Publish a notification about name and update the state.

You must call state_bind() before using this function.

Parameters

name	The name to generate a notification for
state	The new state to report
len	The length of the state variable

Returns

0 if successful, or -1 if an error occurs.

Examples:

publisher.dox.

int state_subscribe

(

const char *

name

)

Subscribe to notifications about a name.

Parameters

name	The name of interest

Returns

0 if successful, or -1 if an error occurs.

Examples:

subscriber.dox.

int state_unbind

(

const char *

name

)

Stop publishing information about <name>

Parameters

name	the name to unbind

Returns

0 if successful, or -1 if an error occurs.

int state_unsubscribe

(

const char *

name

)

Stop subscribing to notifications about <name>

Returns

0 if successful, or -1 if an error occurs.