Shared Memory Management

Shared Memory Management —

Synopsis


#include <monitor/monitor.h>



            mon_shm_header;
            mon_shm_rbuf;
            mon_shm_desc;
enum        mon_shm_impl;
mon_shm_desc* mon_shm_new                   (size_t size,
                                             mon_ipc_creds *peer,
                                             mon_shm_impl impl);
void        mon_shm_done                    (mon_shm_desc *desc);
void        mon_shm_ref                     (mon_shm_desc *desc);
int         mon_shm_lock                    (mon_shm_desc *desc);
int         mon_shm_unlock                  (mon_shm_desc *desc);
int         mon_shm_trylock                 (mon_shm_desc *desc);
int         mon_shm_encode                  (mon_shm_desc *desc,
                                             mon_buffer *buf);
mon_shm_desc* mon_shm_decode                (mon_buffer *buf,
                                             size_t size);
void*       mon_shm_addr                    (mon_shm_desc *desc,
                                             size_t offset);
#define     MON_SHM_ADDR                    (desc, field)
int         mon_shm_data_alloc              (mon_shm_desc *desc,
                                             size_t size,
                                             void **ptr);
void        mon_shm_rbuf_append             (mon_shm_rbuf *rbuf,
                                             void *shmaddr,
                                             void *src,
                                             size_t srclen);
void        mon_shm_rbuf_read               (mon_shm_rbuf *rbuf,
                                             void *shmaddr,
                                             void *dst,
                                             size_t dstlen);
void        mon_shm_rbuf_skip               (mon_shm_rbuf *rbuf,
                                             size_t datalen);
size_t      mon_shm_rbuf_avail              (mon_shm_rbuf *rbuf);
size_t      mon_shm_rbuf_len                (mon_shm_rbuf *rbuf);

Description

Details

mon_shm_header

typedef struct {
	/* Total size of the shared memory area */
	size_t			size;

	/* Beginning of the "Common Data" area */
	size_t			cdata_begin;
	/* End of the "Common Data" area */
	size_t			cdata_end;

	mon_shm_rbuf		rbuf;
} mon_shm_header;

Defines the contents of a shared memory segment. This structure is placed at the beginning of the segment.

size_t `size`;	the size of the shared memory segment.
size_t `cdata_begin`;	offset of the beginning of the common data area.
size_t `cdata_end`;	offset of the end of the common data area.
mon_shm_rbuf `rbuf`;	ring buffer offsets.

mon_shm_rbuf

typedef struct {
	/* Beginning of the ring buffer */
	size_t			begin;
	/* End of the ring buffer */
	size_t			end;
	/* Start of data in the ring buffer */
	size_t			head;
	/* End of data in the ring buffer */
	size_t			tail;
} mon_shm_rbuf;

Defines the contents of a ring buffer.

size_t `begin`;	beginning of the ring buffer area.
size_t `end`;	end of the ring buffer area.
size_t `head`;	offset of the first data byte in the ring buffer.
size_t `tail`;	offset of the first free byte in the ring buffer. Note `head` == `tail` means the ring buffer is empty

mon_shm_desc

typedef struct {
	/* This points to the beginning of the shared memory area */
	mon_shm_header		*header;
	/* Shared memory implementation code */
	mon_shm_impl		impl;

	/* Should be the same as header->size but cannot be modified by the
	 * peer */
	size_t			orig_size;

	/* Implementation-specific private data */
	void			*priv;

	int			is_master;

	/* Methods */
	void			(*destroy)(mon_shm_desc *desc);
	int			(*lock)(mon_shm_desc *desc);
	int			(*unlock)(mon_shm_desc *desc);
	int			(*trylock)(mon_shm_desc *desc);
	int			(*encode)(mon_shm_desc *desc, mon_buffer *buf);

	int			refcnt;
} mon_shm_desc;

Descriptor for a shared memory segment.

mon_shm_header *`header`;	poinsts to the `mon_shm_header` at the beginning of the segment.
mon_shm_impl `impl`;	the underlying implementation this descriptor uses.
size_t `orig_size`;	the size of the shared memory segment. Should be the same as `header.size` except it cannot be modified by the peer.
void *`priv`;	implementation-private data.
int `is_master`;	non-zero if this is the master descriptor ('master' is whoever created the segment originally).
`destroy` ()	method for destroying the segment.
`lock` ()	method for locking the segment.
`unlock` ()	method for unlocking the segment.
`trylock` ()	methof for trying to lock the segment if it is not already locked.
`encode` ()	method for encoding the segment's descriptor.
int `refcnt`;	reference counter for the shared memory segment.

enum mon_shm_impl

typedef enum {
	MON_SHM_IMPL_NONE = -1,
	MON_SHM_IMPL_AUTO,
	MON_SHM_IMPL_POSIX,
	MON_SHM_IMPL_SYSV
} mon_shm_impl;

Shared memory implementation codes.

`MON_SHM_IMPL_NONE`	disable shared memory.
`MON_SHM_IMPL_AUTO`	`mon_shm_new()` should select an implementation automatically.
`MON_SHM_IMPL_POSIX`	Posix shared memory with either Posix semaphores or interprocess pthreads mutexes.
`MON_SHM_IMPL_SYSV`	System V shared memory with System V semaphores.

mon_shm_new ()

mon_shm_desc* mon_shm_new                   (size_t size,
                                             mon_ipc_creds *peer,
                                             mon_shm_impl impl);

Allocates a new shared memory segment.

`size` :	the desired size of the segment. The actual size given may be larger if `size` is not a multiple of the page size.
`peer` :	credentials of the peer who will map the segment.
`impl` :	one of the values of mon_shm_impl.
Returns :	a mon_shm_desc or `NULL` if there was an error.

mon_shm_done ()

void        mon_shm_done                    (mon_shm_desc *desc);

Decrements the reference count of a shared memory segment. If the reference count reaches zero, the shared memory segment is unmapped.

desc : a mon_shm_desc.

mon_shm_ref ()

void        mon_shm_ref                     (mon_shm_desc *desc);

Increments the reference count of a shared memory segment.

desc : a mon_shm_desc.

mon_shm_lock ()

int         mon_shm_lock                    (mon_shm_desc *desc);

Locks a shared memory segment.

`desc` :	a mon_shm_desc.
Returns :	0 if successful or an error code.

mon_shm_unlock ()

int         mon_shm_unlock                  (mon_shm_desc *desc);

Unlocks a shared memory segment.

`desc` :	a mon_shm_desc.
Returns :	0 if successful or an error code.

mon_shm_trylock ()

int         mon_shm_trylock                 (mon_shm_desc *desc);

Tries to lock a shared memory segment.

`desc` :	a mon_shm_desc.
Returns :	0 if the lock was acquired, `EAGAIN` if the segment is locked by the peer.

mon_shm_encode ()

int         mon_shm_encode                  (mon_shm_desc *desc,
                                             mon_buffer *buf);

Encodes the parameters of a shared memory segment so that it can be sent to the peer process.

`desc` :	a mon_shm_desc.
`buf` :	the destination buffer.
Returns :	0 if successful or an error code.

mon_shm_decode ()

mon_shm_desc* mon_shm_decode                (mon_buffer *buf,
                                             size_t size);

Decodes the parameters of a shared memory segment and attaches the segment to the address space of the calling process.

`buf` :	a mon_buffer that was filled by `mon_shm_encode()`.
`size` :	the size of the segment that was requested. If it does not match the size of the segment returned, an error message is printed.
Returns :	a mon_shm_desc or `NULL` if there was an error.

mon_shm_addr ()

void*       mon_shm_addr                    (mon_shm_desc *desc,
                                             size_t offset);

`desc` :
`offset` :
Returns :

MON_SHM_ADDR()

#define MON_SHM_ADDR(desc, field) mon_shm_addr(desc, desc->header->field)

`desc` :
`field` :

mon_shm_data_alloc ()

int         mon_shm_data_alloc              (mon_shm_desc *desc,
                                             size_t size,
                                             void **ptr);

`desc` :
`size` :
`ptr` :
Returns :

mon_shm_rbuf_append ()

void        mon_shm_rbuf_append             (mon_shm_rbuf *rbuf,
                                             void *shmaddr,
                                             void *src,
                                             size_t srclen);

Appends data to a ring buffer.

`rbuf` :	the parameters of the ring buffer.
`shmaddr` :	the base address of the shared memory area.
`src` :	pointer to the data to append.
`srclen` :	length of `src`.

mon_shm_rbuf_read ()

void        mon_shm_rbuf_read               (mon_shm_rbuf *rbuf,
                                             void *shmaddr,
                                             void *dst,
                                             size_t dstlen);

Extracts data from a ring buffer.

`rbuf` :	the parameters of the ring buffer.
`shmaddr` :	the base address of the shared memory area.
`dst` :	where to store the data.
`dstlen` :	the length of the data to extract.

mon_shm_rbuf_skip ()

void        mon_shm_rbuf_skip               (mon_shm_rbuf *rbuf,
                                             size_t datalen);

Discards data in a ring buffer.

`rbuf` :	the parameters of the ring buffer.
`datalen` :	amount of data to discard.

mon_shm_rbuf_avail ()

size_t      mon_shm_rbuf_avail              (mon_shm_rbuf *rbuf);

Returns the free space available in a ring buffer.

`rbuf` :	the parameters of a ring buffer.
Returns :	the space available.

mon_shm_rbuf_len ()

size_t      mon_shm_rbuf_len                (mon_shm_rbuf *rbuf);

Returns the amount of data in a ring buffer.

`rbuf` :	the parameters of a ring buffer.
Returns :	the amount of data.