shm.h File Reference

Shared Memory CMX Component, public API. More...

#include <cmw-cmx/common.h>

Include dependency graph for shm.h:

Classes
union	cmx_shm_value_t
	Union for single-slot values. More...
Typedefs
typedef void(*	cmx_string_callback )(const char *buf, size_t len, void *userarg)
	Type of callback function for cmx_shm_get_value_string().
Functions
int	cmx_shm_create (const char *const name, cmx_shm **const cmx_shm_ptr)
	Create a new CMX Component.
int	cmx_shm_open (const int process_id, const char *const name, cmx_shm **const cmx_shm_ptr)
	Open a existing CMX Component.
int	cmx_shm_open_ro (const int process_id, const char *const name, cmx_shm **const cmx_shm_ptr)
	same as cmx_shm_open() but the shared memory is opened read-only.
int	cmx_shm_add_value_single (cmx_shm *const cmx_shm_ptr, const int type, const char *const name)
	Add a single-slot value (INT64,FLOAT64,BOOL).
int	cmx_shm_add_value_string (cmx_shm *const cmx_shm_ptr, const char *const name, const int size)
	Add a string value (CMX_TYPE_STRING).
int	cmx_shm_find_value (cmx_shm *const cmx_shm_ptr, int start, int *value_handle, int *value_type)
	Find next value starting from a index position.
int	cmx_shm_set_value_single (cmx_shm *const cmx_shm_ptr, const int value_handle, const int type, const cmx_shm_value *const value)
	Set a single-slot value.
int	cmx_shm_set_value_string (cmx_shm *const cmx_shm_ptr, const int value_handle, const char *const value, const int len)
	Set a string value.
int	cmx_shm_get_value_single (const cmx_shm *const cmx_shm_ptr, const int value_handle, int *const type, cmx_shm_value *const value, uint64_t *const mtime)
	Read a single slot value.
int	cmx_shm_get_value_string (const cmx_shm *const cmx_shm_ptr, const int value_handle, cmx_string_callback cb, void *const arg, uint64_t *const mtime)
	Read a string value.
int	cmx_shm_get_value_name (const cmx_shm *const cmx_shm_ptr, const int value_handle, char *const buf)
	Read name of a value.
int	cmx_shm_remove_value (cmx_shm *const cmx_shm_ptr, const int value_handle)
	Remove a value from a component.

---

Detailed Description

Shared Memory CMX Component, public API.

---

Typedef Documentation

typedef void(* cmx_string_callback)(const char *buf, size_t len, void *userarg)

Type of callback function for cmx_shm_get_value_string().

Parameters:

	buf	The data buffer. Never try to manipulate this data. It points into cmx-managed shared-memory. It is always terminated with a '\0' but the '\0' is not included in parameter 2.
	len	Size of parameter 1 not including \0
	userarg	User-data, passed as 'arg' in cmx_shm_get_value_string.

See also:

cmx_shm_get_value_string()

---

Function Documentation

int cmx_shm_add_value_single	(	cmx_shm *const	cmx_shm_ptr,
		const int	type,
		const char *const	name
	)

Add a single-slot value (INT64,FLOAT64,BOOL).

Currently there is no check for duplicate names.

Parameters:

	cmx_shm_ptr
	type	Value in cmx_value_type_t
	name	Name of the new value

Returns:

• A CMX value-handle (> 0)
• A CMX error code (< 0)
  • E_CMX_INVALID_ARGUMENT
  • E_CMX_INVALID_PID
  • E_CMX_COMPONENT_FULL

Examples:

/demo/example1.c, /demo/fast-writer.c, and /demo/measure-fail.c.

int cmx_shm_add_value_string	(	cmx_shm *const	cmx_shm_ptr,
		const char *const	name,
		const int	size
	)

Add a string value (CMX_TYPE_STRING).

Currently there is no check for duplicate names.

Parameters:

	cmx_shm_ptr
	name	Name of the new value
	size	no of characters (max. CMX_SHM_MAX_STRING_SZ)

int cmx_shm_create	(	const char *const	name,
		cmx_shm **const	cmx_shm_ptr
	)

Create a new CMX Component.

On success the argument pointer cmx_shm_ptr will set to the CMX Component. Use cmx_shm_unmap() to free it. Use cmx_shm_destroy() to remove it.

Parameters:

	name	Name of the Component with at least 1 and at most (CMX_NAME_SZ-1) characters.
	cmx_shm_ptr

Returns:

• E_CMX_SUCCESS
• E_CMX_INVALID_ARGUMENT
• E_CMX_CREATE_FAILED
• E_NAME_EXISTS

Examples:

/demo/example1.c, /demo/fast-writer.c, and /demo/measure-fail.c.

int cmx_shm_find_value	(	cmx_shm *const	cmx_shm_ptr,
		int	start,
		int *	value_handle,
		int *	value_type
	)

Find next value starting from a index position.

Searchs slots in SET or UPDATE state and returns a value_handle and value_type. The search starts at 'start' and returns on first match. The caller then can continue the search by extracting the index from the value_handle and pass it +1 in argument start.

Parameters:

	cmx_shm_ptr
	start	Position where to start the search.
	value_handle
	value_type

Returns:

• E_CMX_SUCCESS
• or errorcode: TODO

int cmx_shm_get_value_name	(	const cmx_shm *const	cmx_shm_ptr,
		const int	value_handle,
		char *const	buf
	)

Read name of a value.

The name will be read into the user supplied buffer 'buf'. The size have to be at least CMX_NAME_SZ.

Returns:

• E_CMX_INVALID_HANDLE The slot is either free or the handle has changed (more or less the same as a concurrent modification).
• E_CMX_SUCCESS The name is successfully copied to 'buf'.

int cmx_shm_get_value_single	(	const cmx_shm *const	cmx_shm_ptr,
		const int	value_handle,
		int *const	type,
		cmx_shm_value *const	value,
		uint64_t *const	mtime
	)

Read a single slot value.

For strings this function only returns size and next_index/id but not the actual value.

This function first writes the data into the provided variables and after that decided if the call is successful. That means even in case of error you end up with changed out-variables.

Parameters:

	cmx_shm_ptr
	value_handle
[out]	type
[out]	value
[out]	mtime	(may be null)

Returns:

• E_CMX_SUCCESS
• E_CMX_INVALID_ARGUMENT
• E_CMX_INVALID_HANDLE ('value_handle' is invalid)
• E_CMX_CONCURRENT_MODIFICATION (if a write happens during the read)

Note:

Using CMX in realtime applications

Examples:

/demo/measure-fail.c.

int cmx_shm_get_value_string	(	const cmx_shm *const	cmx_shm_ptr,
		const int	value_handle,
		cmx_string_callback	cb,
		void *const	arg,
		uint64_t *const	mtime
	)

Read a string value.

Parameters:

	cmx_shm_ptr
	value_handle
	cb	Callback function. Is invoked for every chunk of data.
	arg	pass user-data to cb
	mtime	(may be null)

int cmx_shm_open	(	const int	process_id,
		const char *const	name,
		cmx_shm **const	cmx_shm_ptr
	)

Open a existing CMX Component.

On success the argument pointer cmx_shm_ptr will set to the CMX Component. Use cmx_shm_unmap() to free it.

Parameters:

	process_id
	name	Name of the Component with at least 1 and at most (CMX_NAME_SZ-1) characters.
	cmx_shm_ptr

Returns:

• E_CMX_SUCCESS
• E_CMX_NOT_FOUND
• E_CMX_INVALID_ARGUMENT
• E_CMX_CORRUPT_SEGMENT (if CMX_TAG mismatch)
• E_CMX_OPERATION_FAILED (component found but failed to attach)

int cmx_shm_open_ro	(	const int	process_id,
		const char *const	name,
		cmx_shm **const	cmx_shm_ptr
	)

same as cmx_shm_open() but the shared memory is opened read-only.

See also:

cmx_shm_open()

int cmx_shm_remove_value	(	cmx_shm *const	cmx_shm_ptr,
		const int	value_handle
	)

Remove a value from a component.

A value referenced by 'value_handle' will be removed from a CMX Component. The type/name/.. is not checked.

Parameters:

	cmx_shm_ptr
	value_handle

Returns:

• E_CMX_SUCCESS
• E_CMX_OPERATION_FAILED (the removal failed. The value-slot remains in OCCUPIED state, this is critical.)
• E_CMX_INVALID_HANDLE
• E_CMX_INVALID_PID
• E_CMX_CONCURRENT_MODIFICATION
• E_CMX_CORRUPT_SEGMENT

int cmx_shm_set_value_single	(	cmx_shm *const	cmx_shm_ptr,
		const int	value_handle,
		const int	type,
		const cmx_shm_value *const	value
	)

Set a single-slot value.

Note:

Using CMX in realtime applications

Examples:

/demo/example1.c, /demo/fast-writer.c, and /demo/measure-fail.c.

int cmx_shm_set_value_string	(	cmx_shm *const	cmx_shm_ptr,
		const int	value_handle,
		const char *const	value,
		const int	len
	)

Set a string value.

This function copies exactly len bytes. Len must be <= size of the value slot.

Note:

Using CMX in realtime applications