High-Level API

Process-oriented helpers that expose config-driven runtime behavior. More...

Data Structures
struct	zcm_proc_data_socket_cfg
	One runtime data socket entry parsed from XML. More...
struct	zcm_proc_type_handler_cfg
	One configured typed request handler signature. More...
struct	zcm_proc_runtime_cfg
	Parsed runtime config for one zcm_proc instance. More...

Macros
#define	ZCM_PROC_TYPE_HANDLER_MAX   32
	Maximum number of <type> handlers supported in one proc config.
#define	ZCM_PROC_TYPE_HANDLER_ARG_MAX   32
	Maximum number of typed arguments parsed for one <type> handler.
#define	ZCM_PROC_DATA_SOCKET_MAX   16
	Maximum number of <dataSocket> entries supported per proc config.
#define	ZCM_PROC_SUB_TOPIC_MAX   16
	Maximum number of SUB topics supported for one SUB data socket.

Typedefs
typedef struct zcm_proc	zcm_proc_t
	Opaque process helper handle.
typedef enum zcm_proc_data_socket_kind	zcm_proc_data_socket_kind_t
	Data socket kind declared in proc runtime config.
typedef struct zcm_proc_data_socket_cfg	zcm_proc_data_socket_cfg_t
	One runtime data socket entry parsed from XML.
typedef enum zcm_proc_type_arg_kind	zcm_proc_type_arg_kind_t
	Supported typed argument kinds parsed from <type format="...">.
typedef struct zcm_proc_type_handler_cfg	zcm_proc_type_handler_cfg_t
	One configured typed request handler signature.
typedef struct zcm_proc_runtime_cfg	zcm_proc_runtime_cfg_t
	Parsed runtime config for one zcm_proc instance.
typedef void(*	zcm_proc_runtime_sub_payload_cb_t) (const char *self_name, const char *source_name, const void *payload, size_t payload_len, void *user)
	Optional callback for bytes received by SUB/PULL data workers.

Enumerations
enum	zcm_proc_data_socket_kind { ZCM_PROC_DATA_SOCKET_PUB = 1 , ZCM_PROC_DATA_SOCKET_SUB = 2 , ZCM_PROC_DATA_SOCKET_PUSH = 3 , ZCM_PROC_DATA_SOCKET_PULL = 4 }
	Data socket kind declared in proc runtime config. More...
enum	zcm_proc_type_arg_kind { ZCM_PROC_TYPE_ARG_TEXT = 1 , ZCM_PROC_TYPE_ARG_DOUBLE = 2 , ZCM_PROC_TYPE_ARG_FLOAT = 3 , ZCM_PROC_TYPE_ARG_INT = 4 }
	Supported typed argument kinds parsed from <type format="...">. More...

Functions
int	zcm_proc_init (const char *name, zcm_socket_type_t data_type, int bind_data, zcm_proc_t **out_proc, zcm_socket_t **out_data)
	Initialize a process: context, node registration, control socket, and optional data socket.
void	zcm_proc_free (zcm_proc_t *proc)
	Tear down and unregister a process created by zcm_proc_init().
zcm_context_t *	zcm_proc_context (zcm_proc_t *proc)
	Access the context owned by a process helper.
zcm_node_t *	zcm_proc_node (zcm_proc_t *proc)
	Access the node helper owned by a process helper.
int	zcm_proc_runtime_load_config (const char *cfg_path, zcm_proc_runtime_cfg_t *cfg)
	Parse and validate a runtime config XML into an in-memory structure.
int	zcm_proc_runtime_bootstrap (const char *cfg_path, zcm_proc_runtime_cfg_t *cfg, zcm_proc_t **out_proc, zcm_socket_t **out_rep)
	Load config and initialize a daemon process/socket pair.
const zcm_proc_type_handler_cfg_t *	zcm_proc_runtime_find_type_handler (const zcm_proc_runtime_cfg_t *cfg, const char *type_name)
	Find a configured TYPE handler by case-insensitive name.
int	zcm_proc_runtime_decode_type_payload (zcm_msg_t *msg, const zcm_proc_type_handler_cfg_t *handler, char *summary, size_t summary_size)
	Decode a message payload according to one TYPE handler signature.
const char *	zcm_proc_runtime_data_role (const zcm_proc_runtime_cfg_t *cfg)
	Return the data role string for configured data sockets.
const char *	zcm_proc_runtime_builtin_ping_request (void)
	Builtin command request literal used by zcm_proc command semantics.
const char *	zcm_proc_runtime_builtin_ping_reply (void)
	Builtin command reply literal for builtin ping requests.
const char *	zcm_proc_runtime_builtin_default_reply (void)
	Builtin default reply literal for unknown text commands.
const char *	zcm_proc_runtime_builtin_reply_for_command (const char *cmd, uint32_t cmd_len)
	Resolve builtin text command reply (PING => PONG, DATA_METRICS => ROLE=NONE;PUB_PORT=-1;PUSH_PORT=-1;PUB_BYTES=-1;SUB_BYTES=-1;PUSH_BYTES=-1;PULL_BYTES=-1;SUB_TARGETS=-;SUB_TARGET_BYTES=-, else OK).
int	zcm_proc_runtime_first_pub_port (const zcm_proc_runtime_cfg_t *cfg, int *out_port)
	Return the first configured PUB data port.
int	zcm_proc_runtime_first_push_port (const zcm_proc_runtime_cfg_t *cfg, int *out_port)
	Return the first configured PUSH data port.
int	zcm_proc_runtime_payload_bytes (const zcm_proc_runtime_cfg_t *cfg, zcm_proc_data_socket_kind_t kind, int *out_bytes)
	Return payload byte count for one data socket kind.
void	zcm_proc_runtime_start_data_workers (zcm_proc_runtime_cfg_t *cfg, zcm_proc_t *proc, zcm_proc_runtime_sub_payload_cb_t on_sub_payload, void *user)
	Start detached background workers for configured data sockets.

Detailed Description

This module is intended for application code that wants to launch and manage zcm_proc style services with minimal boilerplate.

Macro Definition Documentation

ZCM_PROC_DATA_SOCKET_MAX

#define ZCM_PROC_DATA_SOCKET_MAX   16

Definition at line 27 of file zcm_proc_runtime.h.

ZCM_PROC_SUB_TOPIC_MAX

#define ZCM_PROC_SUB_TOPIC_MAX   16

Definition at line 29 of file zcm_proc_runtime.h.

ZCM_PROC_TYPE_HANDLER_ARG_MAX

#define ZCM_PROC_TYPE_HANDLER_ARG_MAX   32

Definition at line 25 of file zcm_proc_runtime.h.

ZCM_PROC_TYPE_HANDLER_MAX

#define ZCM_PROC_TYPE_HANDLER_MAX   32

Definition at line 23 of file zcm_proc_runtime.h.

Typedef Documentation

zcm_proc_runtime_sub_payload_cb_t

typedef void(* zcm_proc_runtime_sub_payload_cb_t) (const char *self_name, const char *source_name, const void *payload, size_t payload_len, void *user)

Parameters

self_name	Name of the current process.
source_name	Source process name from config target.
payload	Received payload bytes.
payload_len	Number of bytes in payload.
user	Opaque user pointer passed to worker startup.

Definition at line 118 of file zcm_proc_runtime.h.

zcm_proc_t

typedef struct zcm_proc zcm_proc_t

Definition at line 21 of file zcm_proc.h.

Enumeration Type Documentation

zcm_proc_data_socket_kind

enum zcm_proc_data_socket_kind

Enumerator
ZCM_PROC_DATA_SOCKET_PUB	Publisher socket (broadcast payload periodically).
ZCM_PROC_DATA_SOCKET_SUB	Subscriber socket (consume payload from one publisher target).
ZCM_PROC_DATA_SOCKET_PUSH	Push socket (send payload to pull peers).
ZCM_PROC_DATA_SOCKET_PULL	Pull socket (receive payload from one push target).

Definition at line 34 of file zcm_proc_runtime.h.

zcm_proc_type_arg_kind

enum zcm_proc_type_arg_kind

Enumerator
ZCM_PROC_TYPE_ARG_TEXT	String/text argument (-t).
ZCM_PROC_TYPE_ARG_DOUBLE	Double argument (-d).
ZCM_PROC_TYPE_ARG_FLOAT	Float argument (-f).
ZCM_PROC_TYPE_ARG_INT	Integer argument (-i).

Definition at line 68 of file zcm_proc_runtime.h.

Function Documentation

zcm_proc_context()

zcm_context_t * zcm_proc_context

(

zcm_proc_t *

proc

)

Parameters

proc	Process handle.

Returns

Context pointer, or NULL when proc is NULL.

zcm_proc_free()

void zcm_proc_free

(

zcm_proc_t *

proc

)

Parameters

proc	Process handle to free. NULL is allowed.

zcm_proc_init()

int zcm_proc_init	(	const char *	name,
		zcm_socket_type_t	data_type,
		int	bind_data,
		zcm_proc_t **	out_proc,
		zcm_socket_t **	out_data )

Parameters

name	Process/service name to register.
data_type	Socket type used for the optional data socket.
bind_data	Non-zero to create and bind a data socket, zero to skip.
out_proc	Output process handle on success.
out_data	Optional output for created data socket.

Returns

0 on success, -1 on failure.

zcm_proc_node()

zcm_node_t * zcm_proc_node

(

zcm_proc_t *

proc

)

Parameters

proc	Process handle.

Returns

Node pointer, or NULL when proc is NULL.

zcm_proc_runtime_bootstrap()

int zcm_proc_runtime_bootstrap	(	const char *	cfg_path,
		zcm_proc_runtime_cfg_t *	cfg,
		zcm_proc_t **	out_proc,
		zcm_socket_t **	out_rep )

This helper sets ZCM_PROC_CONFIG_FILE so zcm_proc internals can read the same XML file.

Parameters

cfg_path	Path to proc config XML.
cfg	Output parsed config.
out_proc	Output process handle.
out_rep	Output REP control socket.

Returns

0 on success, -1 on failure.

zcm_proc_runtime_builtin_default_reply()

const char * zcm_proc_runtime_builtin_default_reply

(

void

)

Returns

Static default reply text (e.g. OK).

zcm_proc_runtime_builtin_ping_reply()

const char * zcm_proc_runtime_builtin_ping_reply

(

void

)

Returns

Static ping reply text (e.g. PONG).

zcm_proc_runtime_builtin_ping_request()

const char * zcm_proc_runtime_builtin_ping_request

(

void

)

Returns

Static ping request text (e.g. PING).

zcm_proc_runtime_builtin_reply_for_command()

const char * zcm_proc_runtime_builtin_reply_for_command	(	const char *	cmd,
		uint32_t	cmd_len )

Parameters

cmd	Command text bytes.
cmd_len	Command length in bytes.

Returns

Static reply literal.

zcm_proc_runtime_data_role()

const char * zcm_proc_runtime_data_role

(

const zcm_proc_runtime_cfg_t *

cfg

)

Possible values include NONE, PUB, SUB, PUSH, PULL, and + combinations (for example: PUB+SUB, PUSH+PULL).

Parameters

cfg	Runtime config.

Returns

Static role string matching configured sockets.

zcm_proc_runtime_decode_type_payload()

int zcm_proc_runtime_decode_type_payload	(	zcm_msg_t *	msg,
		const zcm_proc_type_handler_cfg_t *	handler,
		char *	summary,
		size_t	summary_size )

On success, a human-readable summary is written to summary.

Parameters

msg	Input message with encoded payload values.
handler	Expected type signature used for decoding.
summary	Output text buffer for decoded values.
summary_size	Size of summary in bytes.

Returns

0 on success, -1 on decode/validation error.

zcm_proc_runtime_find_type_handler()

const zcm_proc_type_handler_cfg_t * zcm_proc_runtime_find_type_handler	(	const zcm_proc_runtime_cfg_t *	cfg,
		const char *	type_name )

Parameters

cfg	Runtime config to inspect.
type_name	Type name to match.

Returns

Matching handler pointer, or NULL if not found.

zcm_proc_runtime_first_pub_port()

int zcm_proc_runtime_first_pub_port	(	const zcm_proc_runtime_cfg_t *	cfg,
		int *	out_port )

Parameters

cfg	Runtime config.
out_port	Output resolved PUB port.

Returns

0 on success, -1 if no PUB socket is configured.

zcm_proc_runtime_first_push_port()

int zcm_proc_runtime_first_push_port	(	const zcm_proc_runtime_cfg_t *	cfg,
		int *	out_port )

Parameters

cfg	Runtime config.
out_port	Output resolved PUSH port.

Returns

0 on success, -1 if no PUSH socket is configured.

zcm_proc_runtime_load_config()

int zcm_proc_runtime_load_config	(	const char *	cfg_path,
		zcm_proc_runtime_cfg_t *	cfg )

Parameters

cfg_path	Path to proc config XML.
cfg	Destination runtime config object.

Returns

0 on success, -1 on failure.

zcm_proc_runtime_payload_bytes()

int zcm_proc_runtime_payload_bytes	(	const zcm_proc_runtime_cfg_t *	cfg,
		zcm_proc_data_socket_kind_t	kind,
		int *	out_bytes )

For PUB/PUSH, this returns the configured payload byte count from the first matching data socket. For SUB/PULL, this returns the last received payload byte count observed by runtime workers (starts at 0 when the kind is configured and no payload has been received yet).

Parameters

cfg	Runtime config.
kind	Data socket kind to query.
out_bytes	Output byte count.

Returns

0 on success, -1 when no matching data socket is configured.

zcm_proc_runtime_start_data_workers()

void zcm_proc_runtime_start_data_workers	(	zcm_proc_runtime_cfg_t *	cfg,
		zcm_proc_t *	proc,
		zcm_proc_runtime_sub_payload_cb_t	on_sub_payload,
		void *	user )

PUB/PUSH data sockets allocate TCP ports automatically from the current domain range and write chosen ports back into cfg->data_sockets.

Parameters

cfg	Runtime config to read and update.
proc	Running process handle used by workers.
on_sub_payload	Optional callback invoked for SUB/PULL received payloads.
user	Opaque pointer forwarded to on_sub_payload.