zz_close_callback, zz_exception_callback, zz_idle_callback, zz_mem_callback, zz_pattern_callback, zz_read_callback, zz_write_callback
zz_exit, zz_exiting, zz_fail, zz_finish
zz_init
zz_exit, zz_exiting, zz_finish, zz_idle_callback, zz_main, zz_one_main
zz_alloc, zz_free, zz_mem_callback, zz_mem_ptr, zz_mem_size, zz_mem_sock, zz_send_mem
zz_debug, zz_fail, zz_message, zz_print_errno, zz_warn
zz_op_add_name, zz_op_add_option, zz_op_add_target, zz_op_parse, zz_op_print_help, zz_op_set_usage, zz_op_target_boolean, zz_op_target_help, zz_op_target_int, zz_op_target_string
zz_mem_callback, zz_pattern_callback
zz_send, zz_sendf, zz_send_mem
zz_closed, zz_index, zz_input, zz_inputs, zz_io_string, zz_is_input, zz_open_inputs, zz_open_outputs, zz_output, zz_outputs
zz_alloc - Allocates a segment of shared memory.
zz_close_callback - Sets the close callback for a socket.
zz_closed - Tells whether a socket is closed.
zz_debug - Prints debugging message.
zz_exception_callback - Starts or stops listening for exceptions on a file descriptor.
zz_exit - Puts ZZ into a clean-up state.
zz_exiting - Tells whether zz_exit() has been called.
zz_fail - Prints failure message and exits.
zz_finish - Waits for sent segments to be received by peers before exiting.
zz_free - Detaches a segment of shared memory.
zz_idle_callback - Sets a function to be called frequently by the main loop.
zz_index - Tells which input or output a socket is.
zz_init - Initializes the ZZ library.
zz_input - Returns the handle to an input socket.
zz_inputs - Returns number of input sockets.
zz_io_string - Returns the string "input" or "output" given a socket.
zz_is_input - Tells whether a socket is an input.
zz_main - Enters the ZZ main loop.
zz_mem_callback - Sets the memory receiving callback for a socket.
zz_mem_ptr - Returns pointer to shared memory segment.
zz_mem_size - Returns the size of a shared memory segment.
zz_mem_sock - Returns the socket on which a shared memory segment was received.
zz_message - Prints user message.
zz_one_main - Runs the ZZ main loop once.
zz_op_add_name - Adds a match-string to the current option.
zz_op_add_option - Adds an option, and makes it the current option.
zz_op_add_target - Adds a custom target to the current option.
zz_open_inputs - Returns number of open inputs.
zz_open_outputs - Returns number of open outputs.
zz_op_parse - Parses options given to application.
zz_op_print_help - Prints the help screen.
zz_op_set_usage - Sets usage string.
zz_op_target_boolean - Adds a boolean target to the current option.
zz_op_target_help - Adds a help target to the current option.
zz_op_target_int - Adds an integer target to the current option.
zz_op_target_string - Adds a string target to the current option.
zz_output - Returns the handle to an output socket.
zz_outputs - Returns number of output sockets.
zz_pattern_callback - Registers a string receiving callback for a socket.
zz_print_errno - Reports system error, if any.
zz_read_callback - Starts or stops listening for read events on a file descriptor.
zz_send - Sends a string to a peer.
zz_sendf - Formats and sends a string to a peer.
zz_send_mem - Sends a reference to a shared memory segment to a peer.
zz_warn - Prints warning message.
zz_write_callback - Starts or stops listening for write events on a file descriptor.
zz_alloc | Top |
Name
zz_alloc - Allocates a segment of shared memory.Synopsis
zz_mem *zz_alloc(unsigned long size);Arguments
- size
- Size of segment in bytes
Description
Allocates a segment of shared memory. Returns a handle to the segment. Remember to detach the segment with
zz_free().Categories
Memory management
zz_close_callback | Top |
Name
zz_close_callback - Sets the close callback for a socket.Synopsis
void zz_close_callback( zz_socket *sock, void *user_data, void (*callback)(zz_socket *sock, void *user_data));Arguments
- sock
- Handle to socket
- user_data
- Pointer to pass to callback
- callback
- Pointer to function
Description
The close callback, if set, is called when a channel becomes closed by a peer. The callback is unset if callback == NULL. A typical close callback consists of calling
zz_exit()ifzz_open_inputs()returns zero, which sets ZZ into the clean-up state if there are no more open inputs.Categories
Callback management
zz_closed | Top |
Name
zz_closed - Tells whether a socket is closed.Synopsis
int zz_closed(zz_socket *sock);Arguments
- sock
- Handle to socket
Description
Returns non-zero if the socket is closed. A socket is closed if the peer has exited, and this has been detected by the ZZ library. Broken channels are detected by the main loop and the sending functions.
Categories
Socket management
zz_debug | Top |
Name
zz_debug - Prints debugging message.Synopsis
void zz_debug(const char *fmt, ...);Arguments
- fmt
- printf-style formatting string, followed by arguments
Description
Prints "APPLICATION_NAME (PID) debug: FORMATTED_MESSAGE\n" (pseudocode) on stderr.
zz_debug()is a macro, evaluating to nothing if NDEBUG is defined.Categories
Message printing
zz_exception_callback | Top |
Name
zz_exception_callback - Starts or stops listening for exceptions on a file descriptor.Synopsis
void zz_exception_callback( int fd, void *user_data, void (*callback)(int fd, void *user_data));Arguments
- fd
- File descriptor
- user_data
- Pointer to pass to callback
- callback
- Pointer to function
Description
The ZZ main loop is built around
select(), and allows listening for custom events.zz_exception_callback()sets the callback to invoke when an exception is detected on a file descriptor. The callback is unset if callback == NULL.Categories
Callback management
zz_exit | Top |
Name
zz_exit - Puts ZZ into a clean-up state.Synopsis
void zz_exit(void);Description
Puts ZZ into a clean-up state, which cannot be undone. The main loop will exit, unless references to one or more shared memory segments have been sent to peers but not received and acknowledged by them. In the latter case, the main loop will continue running until all references are acknowledged or those sockets closed. No more strings or segments will be received. File descriptor callbacks will still work.
Categories
Exiting, Main loop
zz_exiting | Top |
Name
zz_exiting - Tells whether zz_exit() has been called.Synopsis
int zz_exiting(void);Description
Returns non-zero if
zz_exit()has been called.Categories
Exiting, Main loop
zz_fail | Top |
Name
zz_fail - Prints failure message and exits.Synopsis
void zz_fail(const char *fmt, ...);Arguments
- fmt
- printf-style formatting string, followed by arguments
Description
Prints "APPLICATION_NAME (PID) error: FORMATTED_MESSAGE\n" (pseudocode) on stderr, and calls exit(1).
Categories
Exiting, Message printing
zz_finish | Top |
Name
zz_finish - Waits for sent segments to be received by peers before exiting.Synopsis
static inline void zz_finish(void);Description
Calls
zz_exit()andzz_main(). Puts ZZ into the clean-up state, which cannot be undone, and waits until all references to shared memory segments sent to peers have been received and acknowledged, or those sockets have been closed. This is vital when usingzz_one_main()rather thanzz_main(). If the application was to exit before a segment has been received by a peer, the segment might be destroyed by the operating system.Categories
Exiting, Main loop
zz_free | Top |
Name
zz_free - Detaches a segment of shared memory.Synopsis
void zz_free(zz_mem *mem);Arguments
- mem
- Handle to segment
Description
Detaches a segment of shared memory. The segment is not actually destroyed until all processes using the segment have exited or detached the segment.
zz_free()will not detach the segment if a reference to it has been sent to one or more peers which have not sent an acknowledgement.Categories
Memory management
zz_idle_callback | Top |
Name
zz_idle_callback - Sets a function to be called frequently by the main loop.Synopsis
void zz_idle_callback(void (*callback)(void));Arguments
- callback
- Pointer to function
Description
If set,
zz_main()will call this function once in everyselect()cycle. It is unset if callback == NULL. Keep this function short (in CPU time), or the application will be less responsive. If set, the application will use all available CPU time. Therefore, unset the callback rather than immediately exiting from it.Categories
Callback management, Main loop
zz_index | Top |
Name
zz_index - Tells which input or output a socket is.Synopsis
int zz_index(zz_socket *sock);Arguments
- sock
- Handle to socket
Description
Returns the index of the socket, starting from zero for both inputs and outputs.
Categories
Socket management
zz_init | Top |
Name
zz_init - Initializes the ZZ library.Synopsis
void zz_init(const char *app_name);Arguments
- app_name
- Name of application
Description
Initializes the ZZ library. It is vital that
zz_init()is called before ANY other facility of the ZZ library is used.Categories
Initialization
zz_input | Top |
Name
zz_input - Returns the handle to an input socket.Synopsis
zz_socket *zz_input(int index);Arguments
- index
- Index in array of inputs
Description
Returns the handle to an input socket. The indices start at zero.
Categories
Socket management
zz_inputs | Top |
Name
zz_inputs - Returns number of input sockets.Synopsis
static inline int zz_inputs(void);Description
Returns number of input sockets, whether open or closed.
Categories
Socket management
zz_io_string | Top |
Name
zz_io_string - Returns the string "input" or "output" given a socket.Synopsis
static inline const char *zz_io_string(zz_socket *sock);Arguments
- sock
- Handle to socket
Description
Returns the string "input" or "output" given a socket. Equivalent to (zz_is_input(sock) ? "input" : "output").
Categories
Socket management
zz_is_input | Top |
Name
zz_is_input - Tells whether a socket is an input.Synopsis
int zz_is_input(zz_socket *sock);Arguments
- sock
- Handle to socket
Description
Returns non-zero if the socket is an input, zero if it is an output.
Categories
Socket management
zz_main | Top |
Name
zz_main - Enters the ZZ main loop.Synopsis
void zz_main(void);Description
Enters the ZZ main loop. ZZ is designed around its main loop, and the main loop is designed to let applications also be designed around it. The main loop listens for input and custom events, and is the place where callbacks are invoked. The main loop either cycles through the idle callback, or blocks until something happens, depending on whether the idle callback is set.
Categories
Main loop
zz_mem_callback | Top |
Name
zz_mem_callback - Sets the memory receiving callback for a socket.Synopsis
void zz_mem_callback( zz_socket *sock, void *user_data, void (*callback)(zz_mem *mem, void *user_data));Arguments
- sock
- Handle to socket
- user_data
- Pointer to pass to callback
- callback
- Pointer to function
Description
Sets the memory receiving callback for a socket. The function is called every time a reference to a shared memory segment is received. An acknowledge is sent automatically. Remember to detach the segment with
zz_free(). The callback is unset if callback == NULL. If the callback is unset, segments will not be attached.Categories
Callback management, Memory management, Receiving
zz_mem_ptr | Top |
Name
zz_mem_ptr - Returns pointer to shared memory segment.Synopsis
static inline void *zz_mem_ptr(zz_mem *mem);Arguments
- mem
- Handle to segment
Description
Returns a pointer to the beginning of a shared memory segment.
Categories
Memory management
zz_mem_size | Top |
Name
zz_mem_size - Returns the size of a shared memory segment.Synopsis
static inline unsigned long zz_mem_size(zz_mem *mem);Arguments
- mem
- Handle to segment
Description
Returns the size of a shared memory segment, in bytes.
Categories
Memory management
zz_mem_sock | Top |
Name
zz_mem_sock - Returns the socket on which a shared memory segment was received.Synopsis
static inline zz_socket *zz_mem_sock(zz_mem *mem);Arguments
- mem
- Handle to segment
Description
Returns a handle to the socket on which a shared memory segment was received, or NULL if the segment was created by the application itself.
Categories
Memory management
zz_message | Top |
Name
zz_message - Prints user message.Synopsis
void zz_message(const char *fmt, ...);Arguments
- fmt
- printf-style formatting string, followed by arguments
Description
Prints "APPLICATION_NAME (PID) message: FORMATTED_MESSAGE\n" (pseudocode) on stderr.
Categories
Message printing
zz_one_main | Top |
Name
zz_one_main - Runs the ZZ main loop once.Synopsis
void zz_one_main(void);Description
Runs the ZZ main loop once, without blocking, whether
zz_exit()has been called or not. The idle callback is not invoked. It is vital thatzz_one_main()is called at regular intervals in applications which are not built aroundzz_main(), even in applications which do nothing but send data. This is because the ZZ library needs to receive acknowledgements for shared memory it has sent references to, or that memory will not be detached, resulting in a memory leak. Do not forget to callzz_finish()when exiting an application which useszz_one_main()instead ofzz_main().Categories
Main loop
zz_op_add_name | Top |
Name
zz_op_add_name - Adds a match-string to the current option.Synopsis
void zz_op_add_name(const char *name);Arguments
- name
- String to match
Description
Adds a match-string, such as "-v" or "--verbose" to the current option in the option parser. Wildcards are not supported.
Categories
Option parsing
zz_op_add_option | Top |
Name
zz_op_add_option - Adds an option, and makes it the current option.Synopsis
void zz_op_add_option(const char *description);Arguments
- description
- Short description of option
Description
Adds an option to the option parser, and makes it the current option.
Categories
Option parsing
zz_op_add_target | Top |
Name
zz_op_add_target - Adds a custom target to the current option.Synopsis
void zz_op_add_target( const char *typename, void *pointer, int num_args, void (*callback)(char **args, void *pointer), void (*print_func)(void *pointer));Arguments
- typename
- What to call the arguments, such as "integer"
- pointer
- Pointer to data
- num_args
- Number of arguments to target
- callback
- Function to extract data
- print_func
- Function to print default value
Description
Adds a custom target to the current option in the option parser. typename appears after the match-strings in the help screen. pointer is the pointer given to callback and print_func. args is an array of strings (part of argv), from where to extract num_args strings. print_func is expected to print the current data (nothing else) on stderr. typename, pointer and print_func may be NULL, and num_args may be zero.
Categories
Option parsing
zz_open_inputs | Top |
Name
zz_open_inputs - Returns number of open inputs.Synopsis
static inline int zz_open_inputs(void);Description
Returns number of input sockets which are not closed.
Categories
Socket management
zz_open_outputs | Top |
Name
zz_open_outputs - Returns number of open outputs.Synopsis
static inline int zz_open_outputs(void);Description
Returns number of output sockets which are not closed.
Categories
Socket management
zz_op_parse | Top |
Name
zz_op_parse - Parses options given to application.Synopsis
void zz_op_parse(int *argcp, char **argv);Arguments
- argcp
- Pointer to argc, or equivalent
- argv
- argv, or equivalent
Description
Parses options given to the application, extracting data from argv. This might print the help screen and call exit(0). argc and the argv array will be modified, so that parsed strings are removed. What remains is argv[0] and all unparsed arguments, if any. Parsing stops when the end of the argv array has been reached, or a string has been encountered which does not match any option. Remember that: 1. Options after the first regular argument will not be parsed. 2. An unmatched string starting with a dash (-) will be treated as a regular argument.
Categories
Option parsing
zz_op_print_help | Top |
Name
zz_op_print_help - Prints the help screen.Synopsis
void zz_op_print_help(void);Description
Prints the help screen, according to the options given to the option parser thus far.
Categories
Option parsing
zz_op_set_usage | Top |
Name
zz_op_set_usage - Sets usage string.Synopsis
void zz_op_set_usage(const char *usage);Arguments
- usage
- String, such as "Usage: foobar [options], with options:"
Description
Sets usage string in option parser, to begin the help screen with.
Categories
Option parsing
zz_op_target_boolean | Top |
Name
zz_op_target_boolean - Adds a boolean target to the current option.Synopsis
void zz_op_target_boolean(int *pointer);Arguments
- pointer
- Pointer to int
Description
Adds a boolean target to the current option in the option parser. The int referenced by pointer is set to 1 if the option is triggered.
Categories
Option parsing
zz_op_target_help | Top |
Name
zz_op_target_help - Adds a help target to the current option.Synopsis
void zz_op_target_help(void);Description
Adds a help target to the current option in the option parser. The help screen is printed and exit(0) called if the option is triggered.
Categories
Option parsing
zz_op_target_int | Top |
Name
zz_op_target_int - Adds an integer target to the current option.Synopsis
void zz_op_target_int(int *pointer);Arguments
- pointer
- Pointer to int
Description
Adds an integer target to the current option in the option parser. The int referenced by pointer is set with
atoi()if the option is triggered.Categories
Option parsing
zz_op_target_string | Top |
Name
zz_op_target_string - Adds a string target to the current option.Synopsis
void zz_op_target_string(char **pointer);Arguments
- pointer
- Pointer to string pointer
Description
Adds a string target to the current option in the option parser. The string pointer referenced by pointer is set to argv[something] if the option is triggered.
Categories
Option parsing
zz_output | Top |
Name
zz_output - Returns the handle to an output socket.Synopsis
zz_socket *zz_output(int index);Arguments
- index
- Index in array of outputs
Description
Returns the handle to an output socket. The indices start at zero.
Categories
Socket management
zz_outputs | Top |
Name
zz_outputs - Returns number of output sockets.Synopsis
static inline int zz_outputs(void);Description
Returns number of output sockets, whether open or closed.
Categories
Socket management
zz_pattern_callback | Top |
Name
zz_pattern_callback - Registers a string receiving callback for a socket.Synopsis
void zz_pattern_callback( zz_socket *sock, char *pattern, void *user_data, void (*callback)(zz_socket *sock, char *string, void *user_data));Arguments
- sock
- Handle to socket
- pattern
- String to match
- user_data
- Pointer to pass to callback
- callback
- Pointer to function
Description
Registers a string receiving callback for a socket. The function is called whenever a string matching pattern (wildcards * and ? are supported) is received on sock. For instance, strings such as "rate 44100" can be received with "rate *" as pattern. string will point to the whole string. Strings which are private to ZZ will not be seen by the callback. The callback is unregistered if callback == NULL.
Categories
Callback management, Receiving
zz_print_errno | Top |
Name
zz_print_errno - Reports system error, if any.Synopsis
void zz_print_errno(void);Description
Prints "APPLICATION_NAME (PID) system error: STRERROR(ERRNO)\n" (pseudocode) on stderr, if errno != 0. All message printing functions call
zz_print_errno()first, therefore this function might not see much application use.Categories
Message printing
zz_read_callback | Top |
Name
zz_read_callback - Starts or stops listening for read events on a file descriptor.Synopsis
void zz_read_callback( int fd, void *user_data, void (*callback)(int fd, void *user_data));Arguments
- fd
- File descriptor
- user_data
- Pointer to pass to callback
- callback
- Pointer to function
Description
The ZZ main loop is built around
select(), and allows listening for custom events.zz_read_callback()sets the callback to invoke when a read event is detected on a file descriptor. The callback is unset if callback == NULL.Categories
Callback management
zz_send | Top |
Name
zz_send - Sends a string to a peer.Synopsis
int zz_send(zz_socket *sock, const char *str);Arguments
- sock
- Handle to socket connecting to peer
- str
- String to send
Description
Sends a string to a peer. Returns zero on success, or -1 if the connection is broken.
Categories
Sending
zz_sendf | Top |
Name
zz_sendf - Formats and sends a string to a peer.Synopsis
int zz_sendf(zz_socket *sock, const char *fmt, ...);Arguments
- sock
- Handle to socket connecting to peer
- fmt
- printf-style formatting string, followed by arguments
Description
Formats and sends a string to a peer. Returns zero on success, or -1 if the connection is broken.
Categories
Sending
zz_send_mem | Top |
Name
zz_send_mem - Sends a reference to a shared memory segment to a peer.Synopsis
int zz_send_mem(zz_socket *sock, zz_mem *mem);Arguments
- sock
- Handle to socket connecting to peer
- mem
- Handle to segment
Description
Sends a reference to a shared memory segment to a peer. Returns zero on success, or -1 if the connection is broken.
Categories
Memory management, Sending
zz_warn | Top |
Name
zz_warn - Prints warning message.Synopsis
void zz_warn(const char *fmt, ...);Arguments
- fmt
- printf-style formatting string, followed by arguments
Description
Prints "APPLICATION_NAME (PID) warning: FORMATTED_MESSAGE\n" (pseudocode) on stderr.
Categories
Message printing
zz_write_callback | Top |
Name
zz_write_callback - Starts or stops listening for write events on a file descriptor.Synopsis
void zz_write_callback( int fd, void *user_data, void (*callback)(int fd, void *user_data));Arguments
- fd
- File descriptor
- user_data
- Pointer to pass to callback
- callback
- Pointer to function
Description
The ZZ main loop is built around
select(), and allows listening for custom events.zz_write_callback()sets the callback to invoke when a write event is detected on a file descriptor. The callback is unset if callback == NULL.Categories
Callback management