Shared memory buffer. More...

#include <ptypes.h>
#include <pmacros.h>
#include <perror.h>

Include dependency graph for pshmbuffer.h:

Typedefs
typedef typedefP_BEGIN_DECLS struct PShmBuffer_	PShmBuffer
	Shared memory buffer opaque data structure. More...

Functions
P_LIB_API PShmBuffer *	p_shm_buffer_new (const pchar name, psize size, PError *error)
	Creates a new PShmBuffer structure. More...

P_LIB_API void	p_shm_buffer_free (PShmBuffer *buf)
	Frees PShmBuffer structure. More...

P_LIB_API void	p_shm_buffer_take_ownership (PShmBuffer *buf)
	Takes ownership of a shared memory buffer. More...

P_LIB_API pint	p_shm_buffer_read (PShmBuffer buf, ppointer storage, psize len, PError *error)
	Tries to read data from a shared memory buffer. More...

P_LIB_API pssize	p_shm_buffer_write (PShmBuffer buf, ppointer data, psize len, PError *error)
	Tries to write data into a shared memory buffer. More...

P_LIB_API pssize	p_shm_buffer_get_free_space (PShmBuffer buf, PError *error)
	Gets free space in the shared memory buffer. More...

P_LIB_API pssize	p_shm_buffer_get_used_space (PShmBuffer buf, PError *error)
	Gets used space in the shared memory buffer. More...

P_LIB_API void	p_shm_buffer_clear (PShmBuffer *buf)
	Clears all data in the buffer and fills it with zeros. More...

Detailed Description

Shared memory buffer.

Author: Alexander Saprykin

A shared memory buffer works like any other buffer but it is built upon a shared memory region instead of the process-only address space. Thus it inherits all the advantages and disadvantages of shared memory behavior. You should read about PShm before using this buffer implementation to understand underlying restrictions.

The shared memory buffer is process-wide and identified by its name across the system, thus it can be opened by any process if it knows its name. Use p_shm_buffer_new() to open the shared memory buffer and p_shm_buffer_free() to close it.

All read/write operations are completely thread- and process-safe, which means that no other synchronization primitive is required, even for inter- process access. A PShm locking mechanism is used for access synchronization.

The buffer is cyclic and non-overridable which means that you wouldn't get buffer overflow and wouldn't override previously written data until reading it.

The read operation checks whether there is any data available and reads it in case of successful check. After reading the data used space in the buffer is marked as free and any subsequent write operation may overwrite it. Thus you couldn't read the same data twice. The read operation is performed with the p_shm_buffer_read() call.

The write operation checks whether there is enough free space available and writes a given memory block only if the buffer has enough free space. Otherwise no data is written. The write operation is performed with the p_shm_buffer_write() call.

Data can be read and written into the buffer only sequentially. There is no way to access an arbitrary address inside the buffer.

You can take ownership of the shared memory buffer with p_shm_buffer_take_ownership() to explicitly remove it from the system after closing. Please refer to the PShm description to understand the intention of this action.

Typedef Documentation

◆ PShmBuffer

typedef typedefP_BEGIN_DECLS struct PShmBuffer_ PShmBuffer

Shared memory buffer opaque data structure.

Function Documentation

◆ p_shm_buffer_clear()

P_LIB_API void p_shm_buffer_clear ( PShmBuffer * buf )

Clears all data in the buffer and fills it with zeros.

Parameters

buf	PShmBuffer to clear.

Since: 0.0.1

◆ p_shm_buffer_free()

P_LIB_API void p_shm_buffer_free ( PShmBuffer * buf )

Frees PShmBuffer structure.

Parameters

buf	PShmBuffer to free.

Since: 0.0.1

Note that a buffer will be completely removed from the system only after the last instance of the buffer with the same name is closed.

◆ p_shm_buffer_get_free_space()

P_LIB_API pssize p_shm_buffer_get_free_space	(	PShmBuffer *	buf,
		PError **	error
	)

Gets free space in the shared memory buffer.

Parameters

	buf	PShmBuffer to check space in.
[out]	error	Error report object, NULL to ignore.

Returns: Free space in bytes in case of success, -1 otherwise.

Since: 0.0.1

◆ p_shm_buffer_get_used_space()

P_LIB_API pssize p_shm_buffer_get_used_space	(	PShmBuffer *	buf,
		PError **	error
	)

Gets used space in the shared memory buffer.

Parameters

	buf	PShmBuffer to check space in.
[out]	error	Error report object, NULL to ignore.

Returns: Used space in bytes in case of success, -1 otherwise.

Since: 0.0.1

◆ p_shm_buffer_new()

P_LIB_API PShmBuffer* p_shm_buffer_new	(	const pchar *	name,
		psize	size,
		PError **	error
	)

Creates a new PShmBuffer structure.

Parameters

	name	Unique buffer name.
	size	Buffer size in bytes, can't be changed later.
[out]	error	Error report object, NULL to ignore.

Returns: Pointer to the PShmBuffer structure in case of success, NULL otherwise.

Since: 0.0.1

If a buffer with the same name already exists then the size will be ignored and the existing buffer will be returned.

◆ p_shm_buffer_read()

P_LIB_API pint p_shm_buffer_read	(	PShmBuffer *	buf,
		ppointer	storage,
		psize	len,
		PError **	error
	)

Tries to read data from a shared memory buffer.

Parameters

	buf	PShmBuffer to read data from.
[out]	storage	Output buffer to put data in.
	len	Storage size in bytes.
[out]	error	Error report object, NULL to ignore.

Returns: Number of read bytes (can be 0 if buffer is empty), or -1 if error occured.

Since: 0.0.1

◆ p_shm_buffer_take_ownership()

P_LIB_API void p_shm_buffer_take_ownership ( PShmBuffer * buf )

Takes ownership of a shared memory buffer.

Parameters

buf	Shared memory buffer.

Since: 0.0.1

If you take ownership of the shared memory buffer, p_shm_buffer_free() will try to completely unlink it and remove from the system. This is useful on UNIX systems, where shared memory can survive an application crash. On the Windows and OS/2 platforms this call has no effect.

The common usage of this call is upon application startup to ensure that the memory segment from the previous crash can be removed from the system. To do that, call p_shm_buffer_new() and check if its condition is normal (used space, free space). If not, take ownership of the shared memory buffer object and remove it with the p_shm_buffer_free() call. After that, create it again.

◆ p_shm_buffer_write()

P_LIB_API pssize p_shm_buffer_write	(	PShmBuffer *	buf,
		ppointer	data,
		psize	len,
		PError **	error
	)

Tries to write data into a shared memory buffer.

Parameters

	buf	PShmBuffer to write data into.
	data	Data to write.
	len	Data size in bytes.
[out]	error	Error report object, NULL to ignore.

Returns: Number of written bytes (can be 0 if buffer is full), or -1 if error occured.

Since: 0.0.1

Note: Write operation is performed only if the buffer has enough space for the given data size.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ PShmBuffer

Function Documentation

◆ p_shm_buffer_clear()

◆ p_shm_buffer_free()

◆ p_shm_buffer_get_free_space()

◆ p_shm_buffer_get_used_space()

◆ p_shm_buffer_new()

◆ p_shm_buffer_read()

◆ p_shm_buffer_take_ownership()

◆ p_shm_buffer_write()