| main | class hierarchy | alphabetical | list | functions | files | tutorial | programs |

smtk::shared_memory Class Reference

a class that interfaces with a shared memory segment More...

Inheritance diagram for smtk::shared_memory:

[legend]List of all members.

Public Member Functions
int	blocking_q_read (void *buf, size_t bytes=0, size_t offset=0)
	block until there is data to read in the queue
int	blocking_read (void *buf, size_t bytes=0, size_t offset=0)
	read blocking until new data comes
void *	blocking_rlock_pointer (bool from_queue=false, int *num_in_q=0)
	block until new data is ready, get a read-lock and a read pointer
int	blocking_wlock (void)
	wait for the signal from the reader and get the write-lock
void *	blocking_wlock_pointer (void)
	wait for the signal from the reader, get the write-lock and return a pointer to shared memory
int	blocking_write (const void *buf, size_t bytes=0, size_t offset=0, const struct timeval *time_stamp=0, int byte_order=__BYTE_ORDER)
	blocking write
int	blocking_write (const void *buf, const struct timeval *time_stamp, int byte_order=__BYTE_ORDER)
	blocking write
arena *	get_arena (void)
	get the arena object associated with this object
char *	get_name (void) const
	get the segment name
size_t	get_size (void) const
	get the segment memory size
shared_memory &	get_time_stamp (struct timeval &tv)
	get time stamp
long double	get_time_stamp (void) const
	get time stamp
unsigned long long	get_write_count (void) const
	get the write count
bool	is_counted (void)
	is the segment write counted
bool	is_invalid (void) const
	see if the object is invalid
bool	is_local_byte_order () const
	Check the byte order of the data that was last read.
bool	is_queued (void)
	is the segment queued
bool	is_time_stamped (void)
	is the segment write time stamped
bool	is_valid (void) const
	see if the object is valid
template<class X>
shared_memory &	operator= (X x)
	write to the current refered array element
shared_memory &	operator[] (int index)
	refer to one array element
int	q_read (void *buf, size_t bytes=0, size_t offset=0)
	read from the queue
int	read (void *buf, size_t bytes=0, size_t offset=0)
	read current values
void *	rlock_pointer (bool from_queue=false, int *num_in_q=0)
	get a read-lock and a read pointer
int	runlock (void)
	release the read lock
int	set_byte_swapping (int element_size)
	make the segment byte swap when needed and sets array element size
int	set_element_size (int element_size)
	make the segment byte swap when needed and sets array element size
int	set_queuing (int length=0)
	make the segment be queued
int	set_signal_writer (void)
	set up to signal blocking writers
int	set_time_stamping (void)
	make the segment be time stamped when it is written
int	set_write_counting (void)
	make the segment be counted when it is written
	shared_memory (const char *segment_name, const char *arena_file=0)
	shared_memory (size_t size, const char *segment_name, const char *arena_file, MODE arena_file_flag)
	shared_memory (size_t size, const char *segment_name, const char *arena_file, mode_t arena_file_mode=0, MODE arena_file_flag=GET)
	shared_memory (size_t size, const char *segment_name, MODE mflag, const char *arena_file=0, mode_t arena_file_mode=0, MODE arena_file_flag=GET)
	shared_memory (size_t size, const char *segment_name, void *init_buff, const char *arena_file, mode_t arena_file_mode=0, MODE arena_file_flag=GET)
	shared_memory (size_t size, const char *segment_name, void *init_buff, MODE mflag=GET, const char *arena_file=0, mode_t arena_file_mode=0, MODE arena_file_flag=GET)
	shared_memory (size_t size, const char *segment_name=0, size_t element_size=0, void *init_buff=0, u_int16_t flags=0, u_int16_t queue_length=0, MODE mflag=GET, const char *arena_file=0, mode_t arena_file_mode=0, MODE arena_file_flag=GET)
int	signal_writer (bool set_counter=true)
	signal blocking writers
int	unblock_read (void)
	unblock a blocking read
int	unset_signal_writer (void)
	remove this object from signaling blocking writers
int	wait_for_write (void)
	wait for data to read
int	wlock (void)
	get the write lock
void *	wlock_pointer (void)
	get the write-lock and return a pointer to shared memory
int	write (const void *buf, const struct timeval *time_stamp, int byte_order=__BYTE_ORDER)
	write
int	write (const void *buf, size_t bytes=0, size_t offset=0, const struct timeval *time_stamp=0, int byte_order=__BYTE_ORDER)
	write
int	wunlock (const struct timeval *time_stamp=0, bool did_write=true)
	finish off the writing and release the write-lock
virtual	~shared_memory (void)
Static Public Attributes
static const u_int16_t	DEFAULT_QUEUE_LENGTH = 10
static const u_int16_t	IS_COUNTED = 004
static const u_int16_t	IS_TIME_STAMPED = 002
Protected Member Functions
template<class T>
T	invalidate (T t)
	invalidate the object
void	invalidate (void)
	invalidate the object
template<class T>
T	validate (T t)
	validate the object
void	validate (void)
	validate the object

---

Detailed Description

a class that interfaces with a shared memory segment

This provides an interface to SmTk shared memory. This shared memory is shared between processes on a computer and may shared between IP networked computers in a manner that is seamless to the SmTk API (application programming interface) user. So programs that use SmTk shared memory become networked programs in a seamless way that is simular to how X windows programs are networked programs without any effort from the program writer.

There are 28 constructor argument possibilities, with the 7 different constructors. It's likely one will suit you.

---

Constructor & Destructor Documentation

shared_memory::shared_memory	(	size_t	size,
		const char *	segment_name = 0,
		size_t	element_size = 0,
		void *	init_buff = 0,
		u_int16_t	flags = 0,
		u_int16_t	queue_length = 0,
		MODE	mflag = GET,
		const char *	arena_file = 0,
		mode_t	arena_file_mode = 0,
		MODE	arena_file_flag = GET
	)

This constructor has the most optional arguments. It is a super-set of all other smtk::shared_memory constructors.

You create and/or connect to a SmTk shared memory segment with the constructor of a smtk::shared_memory object. If the arena file for the shared memory segment does not exist yet it will be created for the (mflag=) GET and CREATE versions of this. If this is successful the inherited method is_valid() will return true.

Parameters:

	size	size of the shared memory segment that the user will use. This is just the size of that the user reads the writes to.
	segment_name	is the name used to refer to the shared memory segment with, so that other programs may refer to it with this name too. There may not be two shared memory segments with the same name in the same shared memory arena file. If segment_name=0 and this shared memory segment is being created, than a name will be assigned and it will begin with "~". There will be other shared memory segments created with a name that begins with "~" as part of the internal structure of the shared memory arena, so it would be good to avoid having names that begin with ~.
	element_size	is the size of an element in an array, if the data in shared memory is an array of elements. For example if the data in shared memory is an array of single precision floats then element_size should be equal to sizeof(float). When element_size is greater than one then any data read that came from the network will be automatically set so that the byte order is the same as the local computer's byte order. Byte order is only a problem if you are sharing memory between computers with different byte orders like between a SGI IRIX computer and an AMD or Intel PC. If your shared memory data is not an array that's fine, but you may have to do your own byte swapping if your sharing memory between computers with different byte orders. See is_local_byte_order().
	init_buff	is a user provided buffer. init_buff will be used to initialize the shared memory segment if it is created. init_buff will be set to the values of the data in the shared memory segment if it exists before the object is created. If init_buff=0 it will be ignored.
	flags	is a bit mask of flags that may be any bit-wise or'd combination of the masks IS_QUEUED, IS_TIME_STAMPED, and IS_COUNTED: Setting the IS_QUEUED bit will make the shared memory be queued. Setting the IS_TIME_STAMPED bit will make the shared memory be time stamped at each write. Setting the IS_COUNTED bit will make the shared memory be counted at each write. See get_time_stamp(), get_write_count(). Setting these shared memory segment properties at the time the shared memory is created can keep the shared memory arena from becoming fragmented, since the size of the segment memory changes when these segment properties change.
	queue_length	may be set to the desired queue length if the shared memory is to be queued. If queue_length=0, and the shared memory queuing is not set yet, the value of DEFAULT_QUEUE_LENGTH will be used for the queue length.
	mflag	If mflag (creation mode flag) is GET then the shared memory segment will be created if they do not exist, else if mflag is CONNECT than the shared memory segment must exist before this call, or else if mflag is CREATE the shared memory segment must not exist before this call and it will be created.
	arena_file	is the arena file that is used to map the shared memory. Using a network mounted file may not work, but that may be an easy way to get reliable networked shared memory. If it works, it may be a little slow. If arena_file=0 the default arena file SMTK_DEFAULT_ARENA_FILE will be used. SMTK_DEFAULT_ARENA_FILE is defined in smtk/config.h. If arena_file!=0 and it is not a full file path the SMTK_DEFAULT_ARENA_DIR will be the directory used. SMTK_DEFAULT_ARENA_DIR and SMTK_DEFAULT_ARENA_FILE are macros defined in smtk/shared_memory_config.h which is included in smtk.h.
	arena_file_mode	specifies the permissions to use in case a new arena file is created. It is modified by the process's umask in the usual way: the permissions of the created arena file are (mode & ~umask). If arena_file_mode=0 the the arena file permissions will be set to SMTK_DEFAULT_ARENA_FILE_MODE being modified by the process's umask in the usual way: the permissions of the created file are (mode & ~umask). SMTK_DEFAULT_ARENA_FILE_MODE is defined in smtk/config.h. arena_file_mode will not have any effect unless you are creating the arena file. (On UNIXes) You can use chmod(1) or chmod(2) to modify the arena file permissions after the file is created.
	arena_file_flag	If arena_file_flag=GET then the shared memory arena file will be created if it does not exist, else if arena_file_flag is CONNECT than the shared memory arena file must exist before this call, or else if arena_file_flag is CREATE the shared memory arena file must not exist before this call and it will be created.

The environment variable SMTK_ARENA_DIR, if set, will override the default arena file directory. The environment variable SMTK_ARENA_FILE, if set, will override the default arena file.

shared_memory::shared_memory	(	size_t	size,
		const char *	segment_name,
		void *	init_buff,
		MODE	mflag = GET,
		const char *	arena_file = 0,
		mode_t	arena_file_mode = 0,
		MODE	arena_file_flag = GET
	)

Alternate constructor. Uses the default element_size=0.

shared_memory::shared_memory	(	size_t	size,
		const char *	segment_name,
		void *	init_buff,
		const char *	arena_file,
		mode_t	arena_file_mode = 0,
		MODE	arena_file_flag = GET
	)

Alternate constructor. Uses the defaults element_size=0 and MODE flag=GET.

shared_memory::shared_memory	(	size_t	size,
		const char *	segment_name,
		MODE	mflag,
		const char *	arena_file = 0,
		mode_t	arena_file_mode = 0,
		MODE	arena_file_flag = GET
	)

Alternate constructor. Uses the defaults element_size=0 and MODE init_buff=0.

shared_memory::shared_memory	(	size_t	size,
		const char *	segment_name,
		const char *	arena_file,
		mode_t	arena_file_mode = 0,
		MODE	arena_file_flag = GET
	)

Alternate constructor. Uses the defaults element_size=0, MODE init_buff=0 and MODE flag=GET.

shared_memory::shared_memory	(	size_t	size,
		const char *	segment_name,
		const char *	arena_file,
		MODE	arena_file_flag
	)

Alternate constructor. Uses the defaults element_size=0, MODE init_buff=0, MODE flag=GET and arena_file_mode=0.

shared_memory::shared_memory	(	const char *	segment_name,
		const char *	arena_file = 0
	)

Connect to a SmTk shared memory segment with this constructor of a smtk::shared_memory object. If the shared memory segment does not exist this object will not be validated.

Parameters:

	segment_name	is the name used to refer to the shared memory segment with, so that other programs may refer to it with this name too.
	arena_file	is the arena file that is used to map the shared memory.

The environment variable SMTK_ARENA_DIR, if set, will override the default arena file directory. The environment variable SMTK_ARENA_FILE, if set, will override the default arena file.

shared_memory::~shared_memory

(

void

)

[virtual]

This destructor does not remove the shared memory segment from the arena file. The shared memory segment is a resource that is shared between processes. See smtk::shared_memory_remove().

---

Member Function Documentation

int shared_memory::blocking_q_read	(	void *	buf,
		size_t	bytes = 0,
		size_t	offset = 0
	)

block until there is data to read in the queue

This call will block wait for a signal from a write or a call to unblock_read(). Do not call rlock() before this.

If the user held a read-lock (rlock()) before calling this the read-lock will be released before this blocks, if it blocks, but the read-lock will be re-acquired before this returns.

Parameters:

	buf	is a user supplied buffer that the data will be read to. This buffer must be as large or larger then the size of the shared memory, as may have been set in the constructor or is returned from get_size().
	bytes	if set is the number of bytes to write to buf. If bytes is set and you need to do many partial reads you want to call rlock() and do the many q_read() calls and than call advance_q() and maybe more q_read() calls and after you get enough or the queue is empty call runlock(). You don't want to use lots of time while holding the read lock between the rlock() call and the runlock() call.
	offset	is the number of bytes from the start of the shared memory data to start reading from.

Returns:

the number of entries in the queue just at the start of this function call. So if 1 is returned than the one entry would have been read from the queue, and so returns 0 if nothing was read because there was no new queue entries to read and this call was interrupted. Returns -1 on error.

int shared_memory::blocking_read	(	void *	buf,
		size_t	bytes = 0,
		size_t	offset = 0
	)

read blocking until new data comes

This will add write counting to the shared memory segment. If you wish to make certain you read all that is written in an asynchronous manner try shared_memory::read_q() or shared_memory::blocking_q_read().

This call will block wait for a signal from a write or a call to unblock_read(). Do not call rlock() before this.

Parameters:

	buf	is a user supplied buffer that the data will be read to. This buffer must be as large or larger then the size of the shared memory, as may have been set in the constructor or is returned from get_size().
	bytes	if set is the number of bytes to write to buf. If bytes is set and you need to do many partial reads you want to call rlock() and do the many q_read() calls and than call advance_q() and maybe more q_read() calls and after you get enough or the queue is empty call runlock(). You don't want to use lots of time while holding the read lock between the rlock() call and the runlock() call.
	offset	is the number of bytes from the start of the shared memory data to start reading from.

Returns:

1 on success, returns 0 if call was interrupted, and returns -1 on error.

void * shared_memory::blocking_rlock_pointer	(	bool	from_queue = false,
		int *	num_in_q = 0
	)

block until new data is ready, get a read-lock and a read pointer

This will make the shared_memory be queued.

Parameters:

	from_queue	If from_queue is true this will return a pointer to the queued data entry.
	num_in_q	If num_in_q is set and from_queue is true the value that num_in_q points to will be written with the number of entries in the queue before this call. If from_queue is false num_in_q will be ignored.

Returns:

a pointer to shared memory on success, 0 on interupt, and (void *)(-1) on error.

int shared_memory::blocking_wlock

(

void

)

wait for the signal from the reader and get the write-lock

This can be used, in place of wlock(), for doing a synchronous writing with shared_memory::operator= and time_stamp will be ignored. See shared_memory::set_time_stamping() and shared_memory::get_time_stamp().

Todo:

add example code here

Returns:

1 on successful sync-ed write-lock was acquired, returns 0 if the call was interrupted by a out of sync reader calling signal_writer() or the writers code called signal_writer(false), and returns -1 on error.

void* smtk::shared_memory::blocking_wlock_pointer

(

void

)

[inline]

wait for the signal from the reader, get the write-lock and return a pointer to shared memory

This can be used, in place of wlock(), for doing a synchronous writing with shared_memory::operator= and time_stamp will be ignored. See shared_memory::set_time_stamping() and shared_memory::get_time_stamp().

Todo:

add example code here

Returns:

a pointer to shared memory on successful sync-ed write-lock was acquired, returns 0 if the call was interrupted by a out of sync reader calling signal_writer() or the writers code called signal_writer(false), and returns (void *)(-1) on error. The returned shared memory pointer is only valid so long as the write-lock is held.

int shared_memory::blocking_write	(	const void *	buf,
		size_t	bytes = 0,
		size_t	offset = 0,
		const struct timeval *	time_stamp = 0,
		int	byte_order = __BYTE_ORDER
	)

blocking write

Parameters:

	buf	is a pointer to the data to copy to shared memory.
	bytes	if set, is the number of bytes to write.
	offset	is the position in bytes in shared memory where to start writing.
	time_stamp	If time_stamp is set this time stamp will be used to time stamp the shared memory entry. If time_stamp is not set and the segment is time stamped then a time stamp will be generated (using gettimeofday(2)) at the time of this call. The default time_stamp=0 is recommended in most local cases. If time stamping is not set the argument time_stamp will be ignored. See shared_memory::set_time_stamping() and shared_memory::get_time_stamp().
	byte_order	is the order of the data you are writing. This is not for local users. Setting byte_order is necessary if you are writing to shared memory from a server that gets data from the network from computers that may have different byte orders. byte_order may be set to __LITTLE_ENDIAN or __BIG_ENDIAN which are defined in the system header file endian.h.

Returns:

1 on successful syncing write, returns 0 if the call was interrupted by a out of sync reader calling signal_writer() or the writers code called signal_writer(false), and returns -1 on error.

int smtk::shared_memory::blocking_write	(	const void *	buf,
		const struct timeval *	time_stamp,
		int	byte_order = __BYTE_ORDER
	)			[inline]

blocking write

Parameters:

	buf	is a pointer to the data to copy to shared memory.
	time_stamp	If time_stamp is set this time stamp will be used to time stamp the shared memory entry. If time_stamp is not set and the segment is time stamped then a time stamp will be generated (using gettimeofday(2)) at the time of this call. The default time_stamp=0 is recommended in most local cases. If time stamping is not set the argument time_stamp will be ignored. See shared_memory::set_time_stamping() and shared_memory::get_time_stamp().
	byte_order	is the order of the data you are writing. This is not for local users. Setting byte_order is necessary if you are writing to shared memory from a server that gets data from the network from computers that may have different byte orders. byte_order may be set to __LITTLE_ENDIAN or __BIG_ENDIAN which are defined in the system header file endian.h.

Returns:

1 on successful syncing write, returns 0 if the call was interrupted by a out of sync reader calling signal_writer() or the writers code called signal_writer(false), and returns -1 on error.

arena* smtk::shared_memory::get_arena

(

void

)

[inline]

get the arena object associated with this object

You should not need this unless you are debugging SmTk code.

Returns:

a pointer to the arena object associated with this object or 0 if this is shared_memory object is not setup.

char* smtk::shared_memory::get_name

(

void

)

const [inline]

get the segment name

Returns:

a pointer to this objects memory.

size_t smtk::shared_memory::get_size

(

void

)

const [inline]

get the segment memory size

Returns:

the users memory size in bytes. That's the size users data for a single entry when the segment is queued.

shared_memory& smtk::shared_memory::get_time_stamp

(

struct timeval &

tv

)

[inline]

get time stamp

Get the time stamp from the last entry read or written. The shared memory segment must be time stamped by using shared_memory::set_time_stamping().

Parameters:

tv

a reference to a struct timeval which will be set to the time stamp from the last call to read() or q_read().

Returns:

a reference to this shared_memory object.

long double smtk::shared_memory::get_time_stamp

(

void

)

const [inline]

get time stamp

Get the time stamp from the last entry read or written. The shared memory segment must be time stamped by using shared_memory::set_time_stamping().

Returns:

the time stamp, from the last call to read() or q_read(), in seconds as a long double.

unsigned long long smtk::shared_memory::get_write_count

(

void

)

const [inline]

get the write count

The shared memory segment must have write counting set using shared_memory::set_write_counting(). Get the write_count from the last entry read or written.

Returns:

the write count from the last entry read.

template<class T>

T smtk::validation::invalidate

(

T

t

)

[inline, protected, inherited]

invalidate the object

Make the object invalid.

Returns:

t the argument the user passed.

void smtk::validation::invalidate

(

void

)

[inline, protected, inherited]

invalidate the object

Make the object invalid.

bool smtk::shared_memory::is_counted

(

void

)

[inline]

is the segment write counted

returns true if the segment is write counted, else returns false.

bool smtk::validation::is_invalid

(

void

)

const [inline, inherited]

see if the object is invalid

Returns:

true if the object is invalid, and false if not.

bool smtk::shared_memory::is_local_byte_order

(

)

const [inline]

Check the byte order of the data that was last read.

If your not using arrays in the shared memory, when you'll have to byte swap the data that you read yourself. Calling is_local_byte_order() after one of the read methods will tell you if you need to byte swap the data.

return true if the data last read was is the local computers byte order, and returns false if it is not in the local computers byte order.

bool smtk::shared_memory::is_queued

(

void

)

[inline]

is the segment queued

returns true if the segment is queued, else returns false.

bool smtk::shared_memory::is_time_stamped

(

void

)

[inline]

is the segment write time stamped

returns true if the segment is write time stamped, else returns false.

bool smtk::validation::is_valid

(

void

)

const [inline, inherited]

see if the object is valid

Returns:

true if the object is valid, and false if not.

template<class X>

shared_memory& smtk::shared_memory::operator=

(

X

x

)

[inline]

write to the current refered array element

This can be more efficient because you do not need to transfer your calculated values to an array, like when you use shared_memory::write(). You just write the array element value by passing a refenence to the type (like float).

You must call wlock() at some point before this and wunlock() at some point after. This presents a more traditional looking interface to distributed shared memory.

Todo:

add example here.

Parameters:

x

Sets the value of the array element in the shared memory to /e x.

Returns:

a reference to this object.

shared_memory& smtk::shared_memory::operator[]

(

int

index

)

[inline]

refer to one array element

Sets the internal pointer to shared memory to array index index. The element size must be set to use this. The element size may be set in the shared_memory() constructor, set_byte_swapping(), or set_element_size(). You must have a write-lock or a read-lock when calling this.

Parameters:

index

is the array index of the array element you will get. If index is too large (index * element_size >= memory_size) you will over-ride the buffer and get undefined results.

Todo:

add example here.

Returns:

a reference to this object.

int shared_memory::q_read	(	void *	buf,
		size_t	bytes = 0,
		size_t	offset = 0
	)

read from the queue

Read the values from the shared memory queue.

Parameters:

	buf	is a user supplied buffer that the data will be read to.
	bytes	if set is the number of bytes to write to buf. If bytes is set and you need to do many partial reads you want to call rlock() and do the many q_read() calls and than call advance_q() and maybe more q_read() calls and after you get enough or the queue is empty call runlock(). You don't want to use lots of time while holding the read lock between the rlock() call and the runlock() call.
	offset	is the number of bytes from the start of the shared memory data to start reading from.

Returns:

the number of entries in the queue just at the start of this function call. So if 1 is returned than the one entry would have been read from the queue, and so returns 0 if nothing was read because there was no new queue entries to read. Returns -1 on error.

int shared_memory::read	(	void *	buf,
		size_t	bytes = 0,
		size_t	offset = 0
	)

read current values

Read the current values from shared memory. If you wish to make certain you read all that is written in an asynchronous manner try shared_memory::read_q() or shared_memory::blocking_q_read().

Parameters:

	buf	is a user supplied buffer that the data will be read to. If bytes is set and you need to do many partial reads you way want to call rlock() and do the many read() calls and after you get enough call runlock(). You don't want to use lots of time while holding the read lock between the rlock() call and the runlock() call.
	bytes	if set is the number of bytes to write to buf.
	offset	is the number of bytes from the start of the shared memory data to start reading from.

Returns:

0 on success and 1 on error.

void * shared_memory::rlock_pointer	(	bool	from_queue = false,
		int *	num_in_q = 0
	)

get a read-lock and a read pointer

Parameters:

	from_queue	If from_queue is true this will return a pointer to the queued data entry, but if there is no queue entry to read the read-lock will not be aquired.
	num_in_q	If num_in_q is set and from_queue is true the value that num_in_q points to will be written with the number of entries in the queue before this call. If from_queue is false num_in_q will be ignored.

Returns:

a pointer to shared memory on success, if from_queue=false returns 0 on error. If from_queue=true this returns a pointer to shared memory entry, 0 if is no entry to read, and returns (void)(-1) there is an error.

int smtk::shared_memory::runlock

(

void

)

[inline]

release the read lock

Todo:

add example code.

Returns:

0 on success and 1 on error.

int shared_memory::set_byte_swapping

(

int

element_size

)

make the segment byte swap when needed and sets array element size

This will fail if the shared memory segment size is not a multiple of element_size. When the shared memory is written to from a networked server, this will cause the shared memory data to be byte swapped automatically. Since the user may make SmTk shared memory any size with array with elements of any size byte swapping can't be done without knowing the array element size. For example to get an array of floats to be automatically byte swapped, when needed, use: shm_object.set_byte_swapping(sizeof(float)). The element size may also be set in smtk::shared_memory constructors, which sets up automatic byte swapping.

Parameters:

element_size

is the size of the element in bytes. The element size may only be set once, but calling this with the same value as the shared memory segment has set already will not return an error.

Returns:

0 on success and 1 on error.

int smtk::shared_memory::set_element_size

(

int

element_size

)

[inline]

make the segment byte swap when needed and sets array element size

This does the same thing that set_byte_swapping() does, but may be easier to remember function name for people setting the element size so that they may use the array writing funtions operator[] and operator=.

Parameters:

element_size

is the size of the element in bytes. The element size may only be set once, but calling this with the same value as the shared memory segment has set already will not return an error.

Returns:

0 on success and 1 on error.

int shared_memory::set_queuing

(

int

length = 0

)

make the segment be queued

Make the shared memory segment be queued.

Parameters:

length

is the requested queue length. If length is smaller than the current queue length it will not be changed.

Returns:

0 on success and 1 on error.

int shared_memory::set_signal_writer

(

void

)

set up to signal blocking writers

Returns:

0 on success and 1 on error.

int shared_memory::set_time_stamping

(

void

)

make the segment be time stamped when it is written

Returns:

0 on success and 1 on error.

int shared_memory::set_write_counting

(

void

)

make the segment be counted when it is written

This sets the shared memory segment up so that each time the shared memory is written to the data written is marked with a count. See shared_memory::get_write_count().

Returns:

0 on success and 1 on error.

int shared_memory::signal_writer

(

bool

set_counter = true

)

signal blocking writers

Parameters:

set_counter

If set_counter is true the write_count from the last reading call will be written to the segment header so that a blocking_write() in some process can see if it's time to write now or not. A writing process may unblock itself by calling this in a signal handler with set_counter set to false.

Returns:

0 on success and 1 on error.

int shared_memory::unblock_read

(

void

)

unblock a blocking read

For use in the signal handler, so that your program may exit when nothing is writing to the shared memory segment and you in a call to one of the blocking read methods blocking_read() or blocking_q_read().

Returns:

0 on success and 1 on error.

int shared_memory::unset_signal_writer

(

void

)

remove this object from signaling blocking writers

Returns:

0 on success and 1 on error.

template<class T>

T smtk::validation::validate

(

T

t

)

[inline, protected, inherited]

validate the object

Make the object valid.

Returns:

t the argument the user passed.

void smtk::validation::validate

(

void

)

[inline, protected, inherited]

validate the object

Make the object valid.

int shared_memory::wait_for_write

(

void

)

wait for data to read

Blocks until there is new data to read in shared memory. The segment will be write counted if it's not already. See set_write_counting(). If the caller has a read-lock or write-lock before this call it will have it after, though it will be released when and if blocking occurs.

Returns:

1 on success, returns 0 if call was interrupted, and returns -1 on error.

int shared_memory::wlock

(

void

)

get the write lock

Getting a write lock is not required before each write(), but may be useful if your doing a set of more than one partial writes. When wlock() is not called, by the user, before write() it is automatically called in write(). wlock() should be followed by a corresponding call to wunlock(). Unless you're doing partial writes it's not recommended to use wlock() and wunlock().

If a user uses wlock() and wulock() before and after a sequence of calls to write() the time_stamp pasted to write will be ignored, and the user should set time_stamp in the call to wunlock().

Returns:

0 on success and 1 on error.

void* smtk::shared_memory::wlock_pointer

(

void

)

[inline]

get the write-lock and return a pointer to shared memory

Getting a write lock is not required before each write(), but may be useful if your doing a set of more than one partial writes. When wlock() is not called, by the user, before write() it is automatically called in write(). wlock() should be followed by a corresponding call to wunlock(). Unless you're doing partial writes it's not recommended to use wlock() and wunlock().

If a user uses wlock() and wulock() before and after a sequence of calls to write() the time_stamp pasted to write will be ignored, and the user should set time_stamp in the call to wunlock().

Returns:

a pointer to shared memory on success and 0 on error. The returned pointer is only valid so long as the write-lock is held.

int smtk::shared_memory::write	(	const void *	buf,
		const struct timeval *	time_stamp,
		int	byte_order = __BYTE_ORDER
	)			[inline]

write

Write to the shared memory segment.

Parameters:

	buf	is a pointer to the data to copy to shared memory.
	time_stamp	If time_stamp is set this time stamp will be used to time stamp the shared memory entry. If time_stamp is not set and the segment is time stamped then a time stamp will be generated (using gettimeofday(2)) at the time of this call. The default time_stamp=0 is recommended in most local cases. If time stamping is not set the argument time_stamp will be ignored. See shared_memory::set_time_stamping() and shared_memory::get_time_stamp().
	byte_order	is the order of the data you are writing. This is not for local users. Setting byte_order is necessary if you are writing to shared memory from a server that gets data from the network from computers that may have different byte orders. byte_order may be set to __LITTLE_ENDIAN or __BIG_ENDIAN which are defined in the system header file endian.h.

Returns:

0 on success and 1 on error.

int shared_memory::write	(	const void *	buf,
		size_t	bytes = 0,
		size_t	offset = 0,
		const struct timeval *	time_stamp = 0,
		int	byte_order = __BYTE_ORDER
	)

write

Write to the shared memory segment.

Parameters:

	buf	is a pointer to the data to copy to shared memory.
	bytes	if set, is the number of bytes to write.
	offset	is the position in bytes in shared memory where to start writing.
	time_stamp	If time_stamp is set this time stamp will be used to time stamp the shared memory entry. If time_stamp is not set and the segment is time stamped then a time stamp will be generated (using gettimeofday(2)) at the time of this call. The default time_stamp=0 is recommended in most local cases. If time stamping is not set the argument time_stamp will be ignored. See shared_memory::set_time_stamping() and shared_memory::get_time_stamp().
	byte_order	is the order of the data you are writing. This is not for local users. Setting byte_order is necessary if you are writing to shared memory from a server that gets data from the network from computers that may have different byte orders. byte_order may be set to __LITTLE_ENDIAN or __BIG_ENDIAN which are defined in the system header file endian.h.

Returns:

0 on success and 1 on error.

int shared_memory::wunlock	(	const struct timeval *	time_stamp = 0,
		bool	did_write = true
	)

finish off the writing and release the write-lock

If a user uses wlock() and wulock() before and after a sequence of calls to write() the time_stamp pasted to write will be ignored, and the user should set time_stamp in the call to wunlock().

Parameters:

	time_stamp	is a time stamp to write.
	did_write	If did_write=true than the appropate actions will be taken, like advancing the queue. If did_write is false then it is assumed that you did not write and the queue will not be advanced, the write count will not be incremented, and so on.

Returns:

0 on success and 1 on error.

---

Member Data Documentation

const u_int16_t smtk::shared_memory::DEFAULT_QUEUE_LENGTH = 10 [static]

constructor bit-mask flag

const u_int16_t smtk::shared_memory::IS_COUNTED = 004 [static]

constructor bit-mask flag

const u_int16_t smtk::shared_memory::IS_TIME_STAMPED = 002 [static]

constructor bit-mask flag

---

The documentation for this class was generated from the following files:

• libsmtk/smtk/shared_memory.h
• libsmtk/shared_memory.cpp
• libsmtk/shared_memory_constructors.cpp
• libsmtk/shared_memory_rw.cpp
• libsmtk/shared_memory_set.cpp

---