Shared Memory Arena application programming interface (API) More...

Macros
#define	SHM_DEFAULT_SPEW_LEVEL "WARN"
	the default spew level More...

#define	SHM_HOMEPAGE "http://shm-arena.sourceforge.net/"
	the Shared Memory Arena homepage URL More...

#define	SHM_PREFIX "/home/lanceman/installed/encap/shm_arena"
	the installation directory prefix for this installation More...

#define	SHM_DEFAULT_ARENA_DIR "/tmp/shm_arena"
	the default arena directory More...

#define	SHM_DEFAULT_ARENA_FILE "arena"
	the default arena file More...

#define	SHM_RW_MODE (S_IRUSR\|S_IWUSR\|S_IRGRP\|S_IWGRP\|S_IROTH\|S_IWOTH)
	a mode with all the read and write bits enabled More...

#define	SHM_WITH_SHM_OPEN (01 << 24)
	shm_arena_create() flag to use shm_open() More...

#define	SHM_ARENA_HAVE_FLOCK (01 << 25)
	shm_arena_create() flag for advisory file lock More...

#define	SHM_USE_GIVEN_PATH (01 << 26)
	shm_arena_create() flag interpting arena file path More...

#define	SHM_ARENA_DEFAULT (01 << 27)
	shm_arena_create() flag for insuring this is the default arena More...

#define	SHM_WITHOUT_RWLOCK (01 << 28)
	shm_get() flag for not having segment read-write lock More...

#define	SHM_TIMESTAMP (01 << 29)
	smq_get() flag for adding a timestamp to entries More...

#define	SHM_UNKNOWN_SIZE ((size_t) -1)
	shm_get() flag for when you don't know the segment size More...

Typedefs
typedef struct shm_arena *	shm_arena_t
	local process arena object More...

typedef struct smq *	smq_t
	shared multi-queue object More...

Functions
void *	shm_get (shm_arena_t arena, size_t size, const char *name, int flags)
	get a shared memory segment More...

ssize_t	shm_size (shm_arena_t arena, const void *ptr)
	get the size of a shared memory segment More...

ssize_t	shm_size_name (shm_arena_t arena, const char *name)
	get the size of a shared memory segment More...

int	shm_remove (shm_arena_t arena, const void *ptr)
	remove a shared memory segment More...

int	shm_remove_name (shm_arena_t arena, const char *name)
	remove a shared memory segment by name More...

char *	shm_name (shm_arena_t arena, const void ptr, char name, size_t name_size)
	get the name of a shared memory segment for a pointer More...

int	shm_wrlock (shm_arena_t arena, const void *ptr)
	acquire an segment write lock More...

int	shm_rdlock (shm_arena_t arena, const void *ptr)
	acquire an segment read lock More...

int	shm_unlock (shm_arena_t arena, const void *ptr)
	release a shared memory segment read-write lock More...

int	shm_rwlock_reset (shm_arena_t arena, const void *ptr)
	reset a segment read-write lock More...

shm_arena_t	shm_arena_create (const char *path, int flags, mode_t mode, size_t min_size)
	create a shared memory arena object More...

int	shm_arena_delete (shm_arena_t arena)
	delete a local shared memory arena object More...

int	shm_arena_destroy (const char *path, int flags)
	destroy a shared memory arena file More...

int	shm_arena_rwlock_reset (shm_arena_t arena)
	reset an arena read-write lock More...

int	shm_arena_wrlock (shm_arena_t arena)
	acquire an arena write lock More...

int	shm_arena_rdlock (shm_arena_t arena)
	acquire an arena read lock More...

int	shm_arena_unlock (shm_arena_t arena)
	release an arena read or write lock More...

int	shm_arena_set_default (const shm_arena_t arena)
	set the local default arena object More...

int	shm_arena_print (shm_arena_t arena)
	print the cotents of a shared memory arena file to stdout More...

int	shm_arena_print_dot (shm_arena_t arena)
	print debug information about a shared memory arena object in this case a dot file that can be made into a graphics image file showing the binary trees of the shared memory segments in the arena file. More...

int	shm_arena_print_list (shm_arena_t arena)

static void *	sm_get (size_t size, const char *name)
	get a shared memory segment More...

static void *	sm_create (size_t size, const char *name)
	create a shared memory segment More...

static void *	sm_connect (size_t size, const char *name)
	connect to a shared memory segment More...

static size_t	sm_size (const void *ptr)
	get the size of a shared memory segment from a pointer More...

static size_t	sm_size_name (const char *name)
	get the size of a shared memory segment from the name More...

static int	sm_remove (const void *ptr)
	remove a shared memory segment using a pointer More...

static int	sm_remove_name (const char *name)
	remove a shared memory segment using the name More...

static char *	sm_name (const void ptr, char name, size_t name_size)
	get the name of a shared memory segment More...

static int	sm_wrlock (const void *ptr)
	acquire a shared memory segment write lock More...

static int	sm_rdlock (const void *ptr)
	acquire a shared memory segment read lock More...

static int	sm_unlock (const void *ptr)
	release a shared memory segment read-write lock More...

static int	sm_arena_wrlock (void)
	acquire an arena write lock More...

static int	sm_arena_rdlock (void)
	acquire an arena read lock More...

static int	sm_arena_unlock (void)
	release an arena read or write lock More...

smq_t	smq_get (shm_arena_t arena, size_t element_size, int q_length, const char *name, int flags)
	get a Shared Multi-Queue object More...

size_t	smq_element_size (smq_t q)
	get the element size of Shared Multi-Queue object More...

int	smq_remove (smq_t q)
	remove a Shared Multi-Queue from the arena More...

int	smq_delete (smq_t q)
	delete the local Shared Multi-Queue object More...

int	smq_rdlock (smq_t q, int num)
	acquire Shared Multi-Queue read-lock More...

int	smq_unblock_rdlock (smq_t q)
	unblock a smq_rdlock() call if needed More...

int	smq_wrlock (smq_t q, int num)
	acquire Shared Multi-Queue write-lock More...

int	smq_unlock (smq_t q)
	release Shared Multi-Queue read or write lock More...

void *	smq_write (smq_t q)
	write an entry into the Shared Multi-Queue More...

void *	smq_poll (smq_t q)
	poll the last entry from the Shared Multi-Queue More...

void *	smq_read (smq_t q)
	read the next entry from the Shared Multi-Queue More...

long double *	smq_timestamp (smq_t q, const void *ptr)
	read or write the time stamp More...

Detailed Description

Shared Memory Arena application programming interface (API)

This documents all the user functions and related macro definitions provided by the Shared Memory Arena library libshm_arena.

All of the functions that start with the prefix sm_ are simple inline wrapper functions of the corresponding functions that start with the prefix shm_ with the arena parameter set to NULL, which means they will use the default shared memory arena.

Macro Definition Documentation

#define SHM_ARENA_DEFAULT (01 << 27)

shm_arena_create() flag for insuring this is the default arena

shm_arena_create() flag that is used to tell this to be the default arena.

Definition at line 144 of file shm_arena.h.

Referenced by shm_arena_create().

#define SHM_ARENA_HAVE_FLOCK (01 << 25)

shm_arena_create() flag for advisory file lock

shm_arena_create() flag to say we already have an advisory file lock on the arena file to cause it not to get an advisory file lock while creating or connecting to the arena file

Definition at line 130 of file shm_arena.h.

Referenced by shm_arena_create().

#define SHM_DEFAULT_ARENA_DIR "/tmp/shm_arena"

the default arena directory

This is the default shared memory arena file directory. This may be overridden by the value of the environment variable of the same name, which is in-turn overridden by arguments that are passed to shm_arena_create().

Definition at line 86 of file shm_arena.h.

#define SHM_DEFAULT_ARENA_FILE "arena"

the default arena file

This is the default shared memory arena file. This may be overridden by the value of the environment variable of the same name, which is in-turn overridden by arguments that are passed to shm_arena_create(). If the full path for the shared memory arena file is not given SHM_DEFAULT_ARENA_DIR will be considered too.

Definition at line 97 of file shm_arena.h.

#define SHM_DEFAULT_SPEW_LEVEL "WARN"

the default spew level

SHM_DEFAULT_SPEW_LEVEL is the default spew level that is configured for this Shared Memory Arena installation. If this is not set to NONE than this level may be overridden with the environment variable SHM_SPEW, with values of SILENT, WARN, INFO, and DEBUG.

Definition at line 64 of file shm_arena.h.

#define SHM_HOMEPAGE "http://shm-arena.sourceforge.net/"

the Shared Memory Arena homepage URL

SHM_HOMEPAGE is the URL for the Shared Memory Arena homepage.

Definition at line 70 of file shm_arena.h.

#define SHM_PREFIX "/home/lanceman/installed/encap/shm_arena"

the installation directory prefix for this installation

SHM_PREFIX is the installation prefix that was set when this package was configured.

Definition at line 77 of file shm_arena.h.

a mode with all the read and write bits enabled

SHM_RW_MODE is handy to use as part of the mode parameter to shm_arena_create().

Definition at line 105 of file shm_arena.h.

Referenced by shm_arena_destroy().

#define SHM_TIMESTAMP (01 << 29)

smq_get() flag for adding a timestamp to entries

smq_get() flag that is used to tell the shared multi-queue to have all entries time-stamped.

Definition at line 158 of file shm_arena.h.

Referenced by smq_get().

#define SHM_UNKNOWN_SIZE ((size_t) -1)

shm_get() flag for when you don't know the segment size

size to pass to shm_get() when you do not know the size of the shared memory segment that you are connecting to. 0 is a valid shared memory segment size.

Definition at line 165 of file shm_arena.h.

Referenced by shm_get(), and smq_get().

#define SHM_USE_GIVEN_PATH (01 << 26)

shm_arena_create() flag interpting arena file path

shm_arena_create() flag to say we do not get smart about finding the arena file path when creating or connecting to the arena file with shm_arena_create(). Also used as a bit mask flag in shm_arena_destroy() to compute the arena file path.

Definition at line 138 of file shm_arena.h.

Referenced by shm_arena_create(), and shm_arena_destroy().

#define SHM_WITH_SHM_OPEN (01 << 24)

shm_arena_create() flag to use shm_open()

shm_arena_create() flag to say use shm_open(3) to open arena file instead of open(2).

If the root of the full path to the shared memory arena is /dev/shm than the shared memory arena file will be in /dev/shm using shm_open() to create it. SHM_DEFAULT_ARENA_DIR and SHM_DEFAULT_ARENA_FILE may be used with files in /dev/shm.

Definition at line 123 of file shm_arena.h.

Referenced by shm_arena_create(), and shm_arena_print().

#define SHM_WITHOUT_RWLOCK (01 << 28)

shm_get() flag for not having segment read-write lock

shm_get() flag that is used to tell not to make a read-write lock for the segment that is being created.

Definition at line 150 of file shm_arena.h.

Referenced by shm_get(), and smq_get().

Typedef Documentation

typedef struct shm_arena* shm_arena_t

local process arena object

This is the local process arena object that is allocated in local process memory using shm_arena_create(). All other shm-arena functions use it at least internally. This data type is intended to be opaque to the user. See shm_get().

Definition at line 185 of file shm_arena.h.

typedef struct smq* smq_t

shared multi-queue object

A shared memory multi-queue object type. This data type is intended to be opaque to the user.

The shared memory multi-queue is a higher level interface than provided shm_* functions that is provided by smq_* functions.

See smq_read(), smq_write(). and smq_get().

Definition at line 196 of file shm_arena.h.

Function Documentation

shm_arena_t shm_arena_create	(	const char *	path,
		int	flags,
		mode_t	mode,
		size_t	min_size
	)

create a shared memory arena object

shm_arena_create() creates a shared shared memory arena object that is associated with a shared memory arena file. The shared memory arena file will be opened, mapped, remapped, expanded or contracted as shared memory is created and destroyed.

If any of the directories in the path to the shared memory arena file do not exist they will be created using with the mode given in mode. The maximum size arena file mapping is 32 gigabytes on 64-bit systems or less if the system limits it. The number of mappings of the arena file will only be limited by the operating system.

By default Shared Memory Arena arena files are mapped to process virtual addresses that the operating system kernel chooses. In general different processes will map the shared memory to different addresses. If a user wishes to have processes map the shared memory to a particular virtual address, maybe the same address in one or more processes, the environment variable SHM_ADDRESS may be used to select that address. This could be handy if one wishes to read and write pointers into shared memory. If the environment variable SHM_ADDRESS is set the starting address of the shared memory mappings will be the equal to the converted value of SHM_ADDRESS, where SHM_ADDRESS is a hex string. Like for example SHM_ADDRESS=0xa0000000. The address must be at a page boundary. This address value is not stored in the arena file so each process that requires like addresses will be required to set SHM_ADDRESS. All shared memory mappings will follow after previous mappings. This function will fail if SHM_ADDRESS is set and the corrisponding address can't be mapped. If the environment variable SHM_ADDRESS is not set this will not happen. The setting of environment variable SHM_ADDRESS only effects mappings in the processes that it is set in, it will not change any data in the shared memory or the arena file. If a user wishes to connect to more than one arena file with SHM_ADDRESS set, the user must reset SHM_ADDRESS after connecting in their code, or

Keep in mind this creates a local arena object of the process that calls this function, but whither or not this creates an associated arena file is depends on flags (see flags description below).

Parameters

path	is the path to the arena file. This must be in a local file system. If the full path is not given the value of SHM_DEFAULT_ARENA_DIR will pre pended to the path. If `path` is NULL then the value of SHM_DEFAULT_ARENA_FILE with the directory SHM_DEFAULT_ARENA_DIR. If SHM_WITH_SHM_OPEN is set in flag, SHM_DEFAULT_ARENA_DIR will be ignored since the root of the directory (likely /dev/shm) will be determined by the operating system. The environment variable SHM_DEFAULT_ARENA_DIR will override the macro SHM_DEFAULT_ARENA_DIR. The environment variable SHM_DEFAULT_ARENA_DIR will not override the path argument to shm_arena_create(), if path is a full path. The environment variable SHM_DEFAULT_ARENA_FILE will override the macro SHM_DEFAULT_ARENA_FILE. If the full path is given in the environment variable SHM_DEFAULT_ARENA_FILE this will override the macro SHM_DEFAULT_ARENA_DIR too. The environment variable SHM_DEFAULT_ARENA_FILE will not override the path argument to shm_arena_create(). If the determined full path starts with /dev/shm the arena file will be created with shm_open().
flags	may include zero or more the following flags bitwise-or'ed together: The parameter flags must include one of the following access modes: O_RDONLY, O_WRONLY, or O_RDWR. These request opening the file read-only, write-only, or read/write, respectively. If you wish to read and write to the shared memory use O_RDWR. Use O_CREAT if the path to the arena file does not exist so it will be created. O_EXCL when used with O_CREAT, if the file already exists shm_arena_create() will fail. If the flag SHM_WITH_SHM_OPEN is set the arena file will be opened with the shm_open() making the shared memory arena file use a POSIX shared memory object. If SHM_WITH_SHM_OPEN is not set and the determined arena file path does not begin with /dev/shm/ this will use open(2) to open the file. If SHM_USE_GIVEN_PATH is set in flags then the path passed in will be used as it would be in open(2) or shm_open(2) and no fancy path resolving or directory creation will be done.
mode	the mode that is used if the file is created. If you don't know what to use set it to SHM_RW_MODE. Your umask will modify the file permissions as in open() or shm_open().
min_size	is to be set if you know that you will be using a total shared memory in this arena of size a page size. You can get the page size from getpagesize(). Last we've checked it was 4 kilobytes. This is not required to be set, so a value of min_size=0 is fine. This will save on the number process memory mappings if you know you will need lots of memory. If the arena file already exists min_size will be ignored. This is only useful if you want to insure that the first shared memory mapping is larger than one page.

Returns: a shared memory arena object pointer or NULL on error and the system error number, errno, will be set. errno will not be set if there was no error.

See also: shm_get(), sm_get().

Definition at line 387 of file arena.c.

References arena_header::alloc_mapnum, arena_header::alloc_offset, arena_header::change_count, shm_arena::change_count, shm_arena::fd, arena_header::flags, arena_header::free_mapnum, arena_header::free_offset, shm_arena::header, mapping_header::length_used, arena_header::magic, arena_header::map_header, mapping_header::map_length, shm_mapping::map_length, shm_arena::mapping, shm_arena::mapping_mutex, arena_header::name_count, arena_header::num_mappings, shm_arena::num_mappings, arena_header::rwlock, shm_arena::rwlock_key, shm_arena::rwlock_mutex, SHM_ARENA_DEFAULT, SHM_ARENA_HAVE_FLOCK, SHM_USE_GIVEN_PATH, SHM_WITH_SHM_OPEN, shm_mapping::start, and shm_arena::user_shm_address.

int shm_arena_delete ( shm_arena_t arena )

delete a local shared memory arena object

This will not effect the shared arena file.

Parameters

arena returned from shm_arena_create() or NULL to use the default arena.

Returns: 0 on success, 1 if the arena object does not exist, and -1 on system errors. In the case of a most system errors this function will still free the arena object data in the process.

Todo:: We should be freeing the memory for the automatic arena locks for all threads here but there is no way to do that for all the threads. They will at least be freed for each thread as they thread exit, so we do not call pthread_key_delete(arena->rwlock_key).

Definition at line 1016 of file arena.c.

References shm_arena::fd, shm_mapping::map_length, shm_arena::mapping, shm_arena::num_mappings, shm_arena::rwlock_key, and shm_mapping::start.

int shm_arena_destroy	(	const char *	path,
		int	flags
	)

destroy a shared memory arena file

Destroy a shared memory arena file. This does just a little more than remove the shared memory arena file using unlink(2). It also finds the full path to the arena, as it was found in shm_arena_create().

Parameters

path	to the arena file. path may be NULL to destroy the default shared memory arena file.
flags	bit-wise or-ed flag with SHM_USE_GIVEN_PATH and/or SHM_WITH_SHM_OPEN. Both are used for computing the arena file path using the rules used in shm_arena_create().

Returns: 0 on success, and -1 on error and sets errno.

Definition at line 1126 of file arena.c.

References shm_arena::fd, arena_header::flags, SHM_RW_MODE, and SHM_USE_GIVEN_PATH.

int shm_arena_print ( shm_arena_t arena )

print the cotents of a shared memory arena file to stdout

This will print all the data structures in the order in which it appears in the arena. Does not print the user data.

Parameters

arena returned from a call to shm_arena_create() or NULL for the default arena

Returns: 0 on success, and -1 if there is a system error. This does not catch the errors from printf(3) calls.

Definition at line 190 of file print.c.

References arena_header::alloc_mapnum, arena_header::alloc_offset, arena_header::change_count, shm_arena::change_count, seg_footer::flags, arena_header::flags, arena_header::free_mapnum, arena_header::free_offset, shm_arena::header, seg_footer::length, mapping_header::length_used, arena_header::magic, mapping_header::map_length, shm_arena::mapping, shm_arena::mapping_mutex, arena_header::num_mappings, shm_arena::num_mappings, SHM_WITH_SHM_OPEN, and shm_mapping::start.

int shm_arena_print_dot ( shm_arena_t arena )

print debug information about a shared memory arena object in this case a dot file that can be made into a graphics image file showing the binary trees of the shared memory segments in the arena file.

Use shm_arena_print_dot() to print the all the shared memory segments in a graph of the AVL binary tree as a dot file to stdout. dot is part of Graphviz: http://www.research.att.com/sw/tools/graphviz/. The program shm_arena_display will display the PNG, if you have dot, and display for from the package Image Magick http://www.imagemagick.org/, installed.

Parameters

arena returned from a call to shm_arena_create(), or NULL for the default arena file

Returns: 0 on success, -1 on error. This does not catch errors from printf(3) which is called in the function.

Definition at line 535 of file print.c.

References arena_header::alloc_mapnum, arena_header::alloc_offset, arena_header::change_count, shm_arena::change_count, arena_header::free_mapnum, arena_header::free_offset, shm_arena::header, arena_header::magic, and shm_arena::mapping_mutex.

int shm_arena_print_list ( shm_arena_t arena )

print a list of the shared memory segments

Prints a list of all shared memory segments in the associated arena file. Prints one segment on eachs line. Prints to standard out.

Parameters

arena an arena object that was returned from a call to shm_arena_create(), or NULL for the default arena.

Returns: 0 on success, and -1 on error.

See also: shm_list, shm_arena_create().

Definition at line 61 of file print.c.

References arena_header::change_count, shm_arena::change_count, seg_footer::flags, shm_arena::header, seg_header::length, mapping_header::length_used, arena_header::magic, shm_arena::mapping, shm_arena::mapping_mutex, shm_arena::num_mappings, shm_mapping::start, and seg_header::user_length.

int shm_arena_rdlock ( shm_arena_t arena )

acquire an arena read lock

Acquire an inter-process read lock associated with the shared memory arena file. This can be called to make a series of operations that access the arena be atomic. shm_get(), shm_size(), shm_remove(), shm_remove_ptr(), and shm_name() will automatically acquire the arena write lock or read lock, depending on which is needed. The arena read-write locks are recursive so that they may be called more than once, but if they are called more than once they must be unlocked the same number of times they are locked.

Parameters

arena returned from shm_arena_create() or NULL to use the default arena.

Returns: 0 on success and errno on error.

See also: sm_arena_rdlock(), shm_arena_unlock(), shm_arena_wrlock().

Definition at line 114 of file lock.c.

Referenced by sm_arena_rdlock().

int shm_arena_rwlock_reset ( shm_arena_t arena )

reset an arena read-write lock

Parameters

arena returned from shm_arena_create() or NULL to use the default arena.

Returns: 0 on success and errno on error.

Todo:: This is not implemented yet. Should fix a broken arena read-write lock.

Definition at line 358 of file lock.c.

int shm_arena_set_default ( const shm_arena_t arena )

set the local default arena object

Parameters

arena returned from shm_arena_create().

Returns: 0 if there is not default arena being replaced or 1 if the default arena has already been set and this is setting it to another value.

Definition at line 56 of file set_default.c.

int shm_arena_unlock ( shm_arena_t arena )

release an arena read or write lock

Release an inter-process read or write lock associated with the shared memory arena file. This is safe to call if you're not sure if you have the lock or not.

shm_get(), shm_size(), shm_remove(), shm_remove_ptr(), and shm_name() will automatically release the arena write-read lock if shm_arena_wrlock() or shm_arena_rdlock() where not called to lock it.

Parameters

arena returned from shm_arena_create() or NULL to use the default arena.

Returns: 0 on success and errno on error.

Definition at line 145 of file lock.c.

Referenced by sm_arena_unlock(), smq_get(), and smq_rdlock().

int shm_arena_wrlock ( shm_arena_t arena )

acquire an arena write lock

Acquire an exclusive inter-process write lock associated with the shared memory arena file. This can be called to make a series of operations that modify the arena be atomic. shm_get(), shm_size(), shm_remove(), shm_remove_ptr(), and shm_name() will automatically acquire the arena write lock or read lock, depending on which is needed. The arena read-write locks are recursive so that they may be called more than once, but if they are called more than once they must be unlocked the same number of times they are locked. You cannot get an arena write lock while holding an an arena read lock, but you may call shm_arena_rdlock() after shm_arena_wrlock(), which is like the converse.

Parameters

arena returned from shm_arena_create() or NULL to use the default arena.

Returns: 0 on success and errno on error.

See also: sm_arena_wrlock(), shm_arena_unlock(), shm_arena_rdlock().

Definition at line 80 of file lock.c.

Referenced by sm_arena_wrlock(), and smq_get().

void* shm_get	(	shm_arena_t	arena,
		size_t	size,
		const char *	name,
		int	flags
	)

get a shared memory segment

shm_get() can allocate and map a shared memory segment. Since a shared memory segment is an inter-process shared resource the segment may have already been allocated in another process so this provides a method to get access to this shared resource wither it needs to be created or not. If the segment exists already we say that you are just connecting to it, which means you a just mapping it to your address space.

shm_arena_rdlock() or shm_arena_wrlock() may be called before this call. If shm_arena_rdlock() or shm_arena_wrlock() is called before this call than shm_arena_unlock() should be called some time after this call. If shm_arena_rdlock() is called than the segment must already exist, otherwise a write-lock (shm_arena_wrlock()) is needed.

Parameters

arena	returned from a call to shm_arena_create() or may be NULL to have an arena found and created for you automatically.
size	is the size of the shared memory segment. If you are just connecting (mapping) to an existing segment a size of SHM_UNKNOWN_SIZE will work if you don't know the size. Zero is a valid size.
name	is the name string that is used to identify the shared memory.
flags	is a bit-wise or-ed set of flags. The three bit masks that have an effect are O_CREAT, O_EXCL and SHM_WITHOUT_RWLOCK. Do not set O_CREAT nor O_EXCL for connecting only. Set O_CREAT and not O_EXCL for connecting or creating. Set O_CREAT\|O_EXCL for creating. Set SHM_WITHOUT_RWLOCK to create a shared memory segment without an assocated inter-process read-write lock; calls to shm_wrlock(), shm_rdlock() and shm_unlock(), will only get an arena read lock and not a segment lock, since there will be none to get in this if SHM_WITHOUT_RWLOCK was set.

Returns: a pointer to a pointer to the the shared memory segment, or NULL on error. If the shared memory exists and size was set to SHM_UNKNOWN_SIZE and flags does not have the O_CREAT bit set, then errno will not be set, otherwise errno will be set if NULL is returned.

See also: sm_get(), shm_get, sm_create(), sm_connect().

Todo:: We could make a fancier segment name generator for the case when name is not set.

Definition at line 437 of file get.c.

References arena_header::change_count, shm_arena::change_count, shm_arena::header, shm_arena::mapping_mutex, arena_header::name_count, SHM_UNKNOWN_SIZE, SHM_WITHOUT_RWLOCK, and seg_header::user_length.

Referenced by sm_connect(), sm_create(), sm_get(), and smq_get().

char* shm_name	(	shm_arena_t	arena,
		const void *	ptr,
		char *	name,
		size_t	name_size
	)

get the name of a shared memory segment for a pointer

Get the name of a shared memory segment using a pointer to the shared memory segment.

Parameters

arena	returned from a call to shm_arena_create() or may be NULL to use the default shared memory arena.
ptr	is a pointer to the shared memory segment as returned from shm_get(), sm_get(), sm_connect(), or sm_create().
name	is a pointer to memory that the user provided or NULL if memory is to be allocated with malloc().
name_size	is the size that of the memory pointed to by name which was provided by the user.

Returns: a pointer to the name string, or NULL if name_size was not large enough and errno is not set, or NULL if there is a system error and errno will be set.

See also: sm_name(), shm_size().

Todo:: check that this ptr is in one of the shared memory regions.

Definition at line 227 of file size_name.c.

References arena_header::change_count, shm_arena::change_count, shm_arena::header, seg_header::length, and shm_arena::mapping_mutex.

Referenced by sm_name(), and smq_get().

int shm_rdlock	(	shm_arena_t	arena,
		const void *	ptr
	)

acquire an segment read lock

Acquire a non-exclusive inter-process write lock associated with the a shared memory segment. This also locks between intra-process threads.

If successful this will: first acquire an arena file read lock, if the arena object does not have it already, then second this will acquire a segment read lock, if this segment has one.

Parameters

arena	returned from shm_arena_create() or NULL to use the default arena.
ptr	pointer to the shared memory returned from a call to shm_get(), sm_get(), sm_connect(), or sm_create().

Returns: 0 on success and errno on error.

Definition at line 225 of file lock.c.

Referenced by sm_rdlock(), and smq_rdlock().

int shm_remove	(	shm_arena_t	arena,
		const void *	ptr
	)

remove a shared memory segment

shm_remove() will remove a shared memory segment from the associated arena file.

shm_arena_wrlock() may be called before this call. If shm_arena_wrlock() is called before this call than shm_arena_unlock() should be called some time after this call. Since this call will be changing contents and size the arena file getting an arena read-lock with shm_arena_rdlock() will not work.

Parameters

arena	returned from a call to shm_arena_create() or may be NULL to use the default arena.
ptr	is a point that was returned from a call to shm_get(), or other wrapper function.

Returns: 0 on success, 1 if the segment was not found, and -1 on other error.

See also: sm_remove(), shm_remove, shm_get()

Definition at line 312 of file remove.c.

References arena_header::change_count, shm_arena::change_count, shm_arena::header, mapping_header::length_used, shm_arena::mapping, shm_arena::num_mappings, and shm_mapping::start.

Referenced by sm_remove(), smq_get(), and smq_remove().

int shm_remove_name	(	shm_arena_t	arena,
		const char *	name
	)

remove a shared memory segment by name

shm_remove_name() will remove a shared memory segment from the associated arena file.

shm_arena_wrlock() may be called before this call. If shm_arena_wrlock() is called before this call than shm_arena_unlock() should be called some time after this call. Since this call will be changing contents the arena file getting an arena read-lock with shm_arena_rdlock() will not work.

Parameters

arena	returned from a call to shm_arena_create() or may be NULL to use the default arena.
name	is the name of the shared memory segment.

Returns: 0 on success, 1 if the segment was not found, and -1 on other error.

Definition at line 401 of file remove.c.

References arena_header::change_count, shm_arena::change_count, and shm_arena::header.

Referenced by sm_remove_name().

int shm_rwlock_reset	(	shm_arena_t	arena,
		const void *	ptr
	)

reset a segment read-write lock

Parameters

arena	returned from shm_arena_create() or NULL to use the default arena.
ptr	pointer to the shared memory returned from a call to sm_get(), sm_connect(), sm_create(), or shm_get().

Returns: 0 on success and errno on error.

Todo:: This is not implemented yet. Should fix a broken arena read-write lock.

Definition at line 315 of file lock.c.

ssize_t shm_size	(	shm_arena_t	arena,
		const void *	ptr
	)

get the size of a shared memory segment

Get the size of a shared memory segment.

Parameters

arena	returned from a call to shm_arena_create() or may be NULL to have an arena created for you automatically.
ptr	is a pointer to the shared memory segment as returned from shm_get(), sm_get(), sm_connect(), or sm_create().

Returns: the size of the shared memory segment.

See also: shm_size_name(), sm_size().

Todo:: check that this ptr is in one of the shared memory regions.

Definition at line 63 of file size_name.c.

References arena_header::change_count, shm_arena::change_count, shm_arena::header, shm_arena::mapping_mutex, and seg_header::user_length.

Referenced by sm_size(), and smq_get().

ssize_t shm_size_name	(	shm_arena_t	arena,
		const char *	name
	)

get the size of a shared memory segment

Get the size of a shared memory segment using the name.

Parameters

arena	returned from a call to shm_arena_create() or may be NULL to use the default shared memory arena.
name	is the name of the shared memory segment.

Returns: the size of the shared memory segment.

See also: shm_size().

Definition at line 145 of file size_name.c.

References arena_header::change_count, shm_arena::change_count, shm_arena::header, and shm_arena::mapping_mutex.

Referenced by sm_size_name().

int shm_unlock	(	shm_arena_t	arena,
		const void *	ptr
	)

release a shared memory segment read-write lock

Release an inter process write lock that is associated with the a shared memory segment.

Parameters

arena	returned from shm_arena_create() or NULL to use the default arena.
ptr	pointer to the shared memory returned from a call to sm_get(), sm_connect(), sm_create(), or shm_get().

Returns: 0 on success and errno on error.

Definition at line 268 of file lock.c.

Referenced by sm_unlock(), smq_rdlock(), smq_remove(), smq_unlock(), and smq_wrlock().

int shm_wrlock	(	shm_arena_t	arena,
		const void *	ptr
	)

acquire an segment write lock

Acquire an exclusive inter-process read lock associated with the a shared memory segment. This also locks between intra-process threads.

If successful this will: first acquire an arena file read lock, if the arena object does not have on already, then second this will acquire a segment write lock, if this segment has one.

Parameters

arena	returned from shm_arena_create() or NULL to use the default arena.
ptr	pointer to the shared memory returned from a call to shm_get(), shm_get(), sm_connect(), or sm_create().

Returns: 0 on success and errno on error.

Definition at line 177 of file lock.c.

Referenced by sm_wrlock(), and smq_wrlock().

static int sm_arena_rdlock ( void )

inlinestatic

acquire an arena read lock

Acquire an inter-process read lock associated with the default shared memory arena file. This can be called to make a series of operations that access the arena be atomic. sm_get(), sm_size(), sm_size_ptr(), sm_remove(), sm_remove_ptr(), and sm_name() will automatically acquire the arena write lock or read lock, depending on which is needed.

Returns: 0 on success and errno on error.

Definition at line 584 of file shm_arena.h.

References shm_arena_rdlock().

static int sm_arena_unlock ( void )

inlinestatic

release an arena read or write lock

Release an inter-process read or write lock associated with the default shared memory arena file. This is safe to call if you're not sure if you have the lock or not.

sm_get(), sm_size(), sm_size_ptr(), sm_remove(), sm_remove_ptr(), and sm_name() will automatically release the arena write-read lock if sm_arena_wrlock() or sm_arena_rdlock() where not called to lock it.

Returns: 0 on success and errno on error.

Definition at line 603 of file shm_arena.h.

References shm_arena_unlock().

static int sm_arena_wrlock ( void )

inlinestatic

acquire an arena write lock

Acquire an exclusive inter-process write lock associated with the default shared memory arena file. This can be called to make a series of operations that modify the arena be atomic. sm_get(), sm_size(), sm_size_ptr(), sm_remove(), sm_remove_ptr(), and sm_name() will automatically acquire the arena write lock or read lock, depending on which is needed.

Returns: 0 on success and errno on error.

Definition at line 567 of file shm_arena.h.

References shm_arena_wrlock().

static void* sm_connect	(	size_t	size,
		const char *	name
	)

inlinestatic

connect to a shared memory segment

Connects to an existing shared memory segment using the default shared memory arena.

Parameters

size	is the size of the shared memory segment in bytes. If you do not know the size of the segment the size of SHM_UNKNOWN_SIZE will work.
name	is the segment name.

Returns: a pointer to the shared memory, or NULL on error. If the shared memory exists and size was set to SHM_UNKNOWN_SIZE then errno will not be set, otherwise errno will be set if NULL is returned.

See also: sm_get(), sm_create(), sm_connect(), shm_get(), shm_get, sm_remove().

Definition at line 379 of file shm_arena.h.

References shm_get().

static void* sm_create	(	size_t	size,
		const char *	name
	)

inlinestatic

create a shared memory segment

Create a shared memory segment using the default shared memory arena.

sm_arena_wrlock() may be called before this call. If sm_arena_wrlock() is called before this call than sm_arena_unlock() should be called some time after this call.

Parameters

size	is the size of the shared memory segment in bytes. Zero is a valid size.
name	is the name string that is used to identify the shared memory.

Returns: a pointer to a pointer to the shared memory segment.

See also: sm_get().

Definition at line 354 of file shm_arena.h.

References shm_get().

static void* sm_get	(	size_t	size,
		const char *	name
	)

inlinestatic

get a shared memory segment

sm_get() can allocate and map a shared memory segment. Since a shared memory segment is an inter-process shared resource the segment may have already been allocated in another process so this provides a method to get access to this shared resource wither it needs to be created or not.

sm_arena_rdlock() or sm_arena_wrlock() may be called before this call. If sm_arena_rdlock() or sm_arena_wrlock() is called before this call than sm_arena_unlock() should be called some time after this call. If sm_arena_rdlock() is called than the segment must already exist, otherwise a write-lock (sm_arena_wrlock()) is needed.

Parameters

size	is the size of the shared memory segment in bytes. Zero is a valid size.
name	is the name string that is used to identify the shared memory.

Returns: a pointer to a pointer to the shared memory segment, or NULL on error.

See also: shm_get(), shm_get, sm_create(), sm_connect(), sm_remove(), example code examples/tutorial/read.c tutorial example Reading Shared Memory Segments

Definition at line 329 of file shm_arena.h.

References shm_get().

static char* sm_name	(	const void *	ptr,
		char *	name,
		size_t	name_size
	)

inlinestatic

get the name of a shared memory segment

Get the name of a shared memory segment from the default shared memory arena, by using a pointer to the shared memory segment.

Parameters

ptr	is a pointer to the shared memory segment as returned from shm_get(), sm_get(), sm_connect(), or sm_create().
name	is a pointer to memory that the user provided or NULL if memory is to be allocated with malloc().
name_size	is the size that of the memory pointed to by name which was provided by the user.

Returns: a pointer to the name string, or NULL if name_size was not large enough and errno is not set, or NULL if there is a system error and errno will be set.

See also: sm_size_name(), shm_remove, sm_size(), shm_name().

Definition at line 478 of file shm_arena.h.

References shm_name().

static int sm_rdlock ( const void * ptr )

inlinestatic

acquire a shared memory segment read lock

Acquire a non-exclusive inter-process write lock associated with the a shared memory segment, using the default shared memory arena. This also locks between intra-process threads.

Parameters

ptr	pointer to the shared memory returned from a call to sm_get(), sm_connect(), sm_create(), or shm_get().

Returns: 0 on success and errno on error.

See also: shm_rdlock(), sm_unlock(), example code examples/tutorial/read.c tutorial example Reading Shared Memory Segments

Definition at line 524 of file shm_arena.h.

References shm_rdlock().

static int sm_remove ( const void * ptr )

inlinestatic

remove a shared memory segment using a pointer

Remove a shared memory segment from the default shared memory arena.

Parameters

ptr	is a pointer to the shared memory segment.

Returns: 0 on success, 1 if the segment was not found, and -1 on other error.

See also: sm_remove_name(), shm_remove, sm_get(), shm_remove().

Definition at line 433 of file shm_arena.h.

References shm_remove().

static int sm_remove_name ( const char * name )

inlinestatic

remove a shared memory segment using the name

Remove a shared memory segment from the default shared memory arena, by using the name of the segment.

Parameters

name	is the name of the segment.

Returns: 0 on success, 1 if the segment was not found, and -1 on other error.

See also: sm_remove(), sm_get(), shm_remove(), shm_remove.

Definition at line 451 of file shm_arena.h.

References shm_remove_name().

static size_t sm_size ( const void * ptr )

inlinestatic

get the size of a shared memory segment from a pointer

Get the size of a shared memory segment using the default shared memory arena.

Parameters

ptr	is a pointer to the shared memory segment.

Returns: the size of the shared memory segment in bytes.

See also: sm_get(), sm_create(), shm_get(), sm_size_name().

Definition at line 396 of file shm_arena.h.

References shm_size().

static size_t sm_size_name ( const char * name )

inlinestatic

get the size of a shared memory segment from the name

Get the size of a shared memory segment from the name, using the default shared memory arena.

Parameters

name	is the name of the shared memory segment.

Returns: the size of the shared memory segment in bytes.

See also: sm_get(), sm_create(), shm_get(), sm_name().

Definition at line 414 of file shm_arena.h.

References shm_size_name().

static int sm_unlock ( const void * ptr )

inlinestatic

release a shared memory segment read-write lock

Release an inter-process read lock associated with the a shared memory segment, using the default shared memory arena. This also locks between intra-process threads.

Parameters

ptr	pointer to the shared memory returned from a call to sm_get(), sm_connect(), sm_create(), or shm_get().

Returns: 0 on success and errno on error.

See also: shm_unlock(), sm_rdlock(), sm_wrlock(), example code: examples/tutorial/write.c, examples/tutorial/write.c, tutorial example Writing Shared Memory Segments, Reading Shared Memory Segments.

Definition at line 548 of file shm_arena.h.

References shm_unlock().

static int sm_wrlock ( const void * ptr )

inlinestatic

acquire a shared memory segment write lock

Acquire an exclusive inter-process write lock associated with the a shared memory segment, using the default shared memory arena. This also locks between intra-process threads.

Parameters

ptr	pointer to the shared memory returned from a call to sm_get(), sm_connect(), sm_create(), or shm_get().

Returns: 0 on success and errno on error.

See also: shm_wrlock(), sm_unlock(), example code examples/tutorial/write.c tutorial example Writing Shared Memory Segments

Definition at line 501 of file shm_arena.h.

References shm_wrlock().

int smq_delete ( smq_t q )

delete the local Shared Multi-Queue object

This will not affect the Multi-Queue data in the shared memory arena. This will free memory for the local Shared Multi-Queue object. The local Shared Multi-Queue object will no longer be usable after this call. This will wait for any quick cleanup threads spawned from smq_unblock_rdlock().

Parameters

q	is a Multi-Queue object that was returned from a call to smq_get().

Returns: 0 on success and non-zero on error.

Definition at line 810 of file smq.c.

size_t smq_element_size ( smq_t q )

get the element size of Shared Multi-Queue object

You are required to have a least a read lock, via smq_rdlock(), before calling this.

Parameters

q	is a Multi-Queue object that was returned from a call to smq_get().

Returns: the element size in bytes.

Definition at line 792 of file smq.c.

smq_t smq_get	(	shm_arena_t	arena,
		size_t	element_size,
		int	q_length,
		const char *	name,
		int	flags
	)

get a Shared Multi-Queue object

A Shared Multi-Queue object (smq_t) is a queue that is built using a Shared memory segment(s). So the queue is shared between unrelated (or related) processes. Read-write locks are used to keep the data in the queue consistent. The queue is a ring buffer or circular queue so you need to understand how your read rates and write rates are related. If you will be reading at a rate that is at least one tenth the rate at which you are writing then your queue length should be at least ten, so you do not lose data. The read rate refers to how often the many queue entries are flushed (all quickly read in one loop). The queue is a Multi-Queue in that all queue objects may read all the data in the queue. It's like all objects in all threads (or processes) can read all the data that was ever written. They all keep their own read indexes into the queue and the write index is shared. If any reader reads too slow than the queue will wrap and that reader will miss data entries. The queue length will grow to accommodate the largest requested queue length.

Todo:: Shared Multi-Queue blocking write functionality is not written yet, but Shared Multi-Queue blocking read is working fine and is preferred to using usleep(3) or sleep(3). See blocking read example code smq_blocking_read.c.

Parameters

arena	a shared memory arena object or NULL to use the default arena.
element_size	the length in bytes of an entry in the Multi-Queue. If you don't know the size or an existing Shared Multi-queue you can use SHM_UNKNOWN_SIZE.
q_length	the requested length of the Multi-Queue. This will be the maximum number entries that the queue can hold before it wraps. When `q_length` is larger than an the length of an existing Multi-Queue with this name the Multi-Queue changes its length to `q_length`.
name	is the name of the Multi-Queue.
flags	are used to determine whither to create or just connect to the queue, the same as in shm_get(). The `q_length` will effect maximum number of elements in the Multi-Queue even it `flags` is such that is not creating the Shared Multi-Queue. In addition setting the SHM_TIMESTAMP bit will cause the entries to be time-stamped as they are written.

Shared Multi-Queue objects are not thread safe to the same extent that shared memory arena segments are. We don't know of a driving reason to make a Shared Multi-Queue object that is shared between threads in one process. You may make a Shared Multi-Queue object that connects to the same Shared Multi-Queue for each thread. It will be safe to use any number of Shared Multi-Queue objects in different threads, so long as different threads do not access the same Shared Multi-Queue objects at the same time.

Returns: a Shared Multi-Queue object which can be used to lock, and read and write the Multi-Queue entries. Returns NULL on error and sets errno.

See also: shm_arena_create(), smq_rdlock(), smq_wrlock(), smq_read(), smq_write(), and example code smq_blocking_read.c, smq_read.c.

Definition at line 358 of file smq.c.

References shm_arena_unlock(), shm_arena_wrlock(), shm_get(), shm_name(), shm_remove(), shm_size(), SHM_TIMESTAMP, SHM_UNKNOWN_SIZE, and SHM_WITHOUT_RWLOCK.

void* smq_poll ( smq_t q )

poll the last entry from the Shared Multi-Queue

This reads the last entry written to the Multi-Queue object and empties this queue object, but not all Multi-Queue objects.

Parameters

q	is a Multi-Queue object that was returned from a call to smq_get().

Returns: a pointer to the entry that the user can read, or NULL if there is no entries to read yet.

See also: smq_read(), smq_rdlock(), smq_get().

Definition at line 1229 of file smq.c.

int smq_rdlock	(	smq_t	q,
		int	num
	)

acquire Shared Multi-Queue read-lock

The Shared Multi-Queue read-lock is a shared between other threads getting a read-lock on the same Shared Multi-Queue object, but excludes Shared Multi-Queue write-locks from being acquired in other threads. If there is contention with a write lock this call will block until there is no contention with a write lock, for all values of num.

Parameters

q	is a Multi-Queue object that was returned from a call to smq_get().
num	if greater than zero the call will block until there is `num` entries to read or smq_unblock_rdlock() is called with this local Multi-Queue object.

Returns: the number of entries that can be read on success, and -1 on error.

See also: example codes smq_read.c, smq_blocking_read.c, and smq_unlock()

Definition at line 881 of file smq.c.

References shm_arena_unlock(), shm_rdlock(), and shm_unlock().

void* smq_read ( smq_t q )

read the next entry from the Shared Multi-Queue

Parameters

q	is a Multi-Queue object that was returned from a call to smq_get().

Returns: a pointer to the entry that the user can read, or NULL if there is no entries to read.

See also: smq_rdlock(), smq_get().

Definition at line 1262 of file smq.c.

int smq_remove ( smq_t q )

remove a Shared Multi-Queue from the arena

This will also delete the local Shared Multi-Queue object. The local Shared Multi-Queue object will no longer be usable after this call.

Parameters

q	is a Multi-Queue object that was returned from a call to smq_get().

Returns: 0 on success and non-zero on error.

Definition at line 717 of file smq.c.

References shm_remove(), shm_unlock(), and smq_wrlock().

long double* smq_timestamp	(	smq_t	q,
		const void *	ptr
	)

read or write the time stamp

Get a pointer to the time stamp. You must have a read lock, from smq_rdlock() or a write lock, from smq_wrlock() to call this.

Parameters

q	is a Multi-Queue object that was returned from a call to smq_get().
ptr	is a pointer that was returned from smq_read() or smq_write().

Returns: a pointer to the entry that the user can read, for the case when the pointer was from smq_read(), or write for the case when the pointer was from smq_write().

See also: example code smq_read_timestamp.c, and smq_read()

Definition at line 1136 of file smq.c.

int smq_unblock_rdlock ( smq_t q )

unblock a smq_rdlock() call if needed

Unblock a smq_rdlock() call so that a program may continue to run when nothing is writing to the Shared Multi-Queue. This will make the next or current smq_rdlock() return if the requested queue entries are present or not. smq_unblock_rdlock() will spawn a thread to do the work for it, since this is intended to be called in a signal handler, and getting a mutex is required to unblock the smq_rdlock() call.

Parameters

q	is a Multi-Queue object that was returned from a call to smq_get().

Returns: 0 on success and error number on error.

See also: example code smq_blocking_read.c, smq_rdlock()

Definition at line 1027 of file smq.c.

int smq_unlock ( smq_t q )

release Shared Multi-Queue read or write lock

The Shared Multi-Queue write-lock is an exclusive lock Shared Multi-Queue object. This will also time stamp the entry if this is called after a smq_write() and the user has not called smq_timestamp() since.

Parameters

q	is a Multi-Queue object that was returned from a call to smq_get().

Returns: 0 on success, and -1 on error.

See also: smq_rdlock(), smq_wrlock(), and example codes smq_blocking_read.c, smq_read.c

Definition at line 1102 of file smq.c.

References shm_unlock().

void* smq_write ( smq_t q )

write an entry into the Shared Multi-Queue

If this Shared Multi-Queue is time-stamped, this will also time stamp the last entry from a previous smq_write() call if this is called after a smq_write() and the user has not called smq_timestamp() or smq_unlock() since that.

Parameters

q	is a Multi-Queue object that was returned from a call to smq_get().

Returns: a pointer to the entry that the user will write to, or NULL on error.

See also: smq_wrlock(), smq_get().

Definition at line 1165 of file smq.c.

int smq_wrlock	(	smq_t	q,
		int	num
	)

acquire Shared Multi-Queue write-lock

The Shared Multi-Queue write-lock is an exclusive lock Shared Multi-Queue object.

Parameters

q	is a Multi-Queue object that was returned from a call to smq_get().
num	this call will block until `num` readers have unlocked since last write lock.

Returns: 0 on success, and -1 on error.

See also: smq_unlock(), example code smq_write.c.

Todo:: For now use num of zero, blocking Shared Multi-Queue write is not implemented yet.

Definition at line 1073 of file smq.c.

References shm_unlock(), and shm_wrlock().

Referenced by smq_remove().

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation