pshm.h File Reference

Shared memory. More...

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

Go to the source code of this file.

Typedefs
typedef enum PShmAccessPerms_	PShmAccessPerms
	Enum with shared memory access permissions. More...
typedef struct PShm_	PShm
	Shared memory opaque data structure. More...

Enumerations
enum	PShmAccessPerms_ { P_SHM_ACCESS_READONLY = 0, P_SHM_ACCESS_READWRITE = 1 }
	Enum with shared memory access permissions. More...

Functions
P_LIB_API PShm *	p_shm_new (const pchar *name, psize size, PShmAccessPerms perms, PError **error)
	Creates a new PShm object. More...
P_LIB_API void	p_shm_take_ownership (PShm *shm)
	Takes ownership of a shared memory segment. More...
P_LIB_API void	p_shm_free (PShm *shm)
	Frees PShm object. More...
P_LIB_API pboolean	p_shm_lock (PShm *shm, PError **error)
	Locks PShm object for usage. More...
P_LIB_API pboolean	p_shm_unlock (PShm *shm, PError **error)
	Unlocks PShm object. More...
P_LIB_API ppointer	p_shm_get_address (const PShm *shm)
	Gets a starting address of a PShm memory segment. More...
P_LIB_API psize	p_shm_get_size (const PShm *shm)
	Gets the size of a PShm memory segment. More...

Detailed Description

Shared memory.

Author

Alexander Saprykin

Shared memory is a memory segment which can be accessed from several threads or processes. It provides an efficient way to transfer large blocks of data between processes. It can be used as any other regular memory segment in an application.

Shared memory acts like an inter-process communication method. This memory exchange implementation is process-wide so you can transfer data not only between the threads. But it makes this IPC method (actually like any other IPC method, as well) relatively heavy. Consider using other approaches instead if you do not need to cross the process boundary.

A shared memory segment doesn't provide any synchronization primitives itself which means that several processes or threads can concurrently write and read from it. This can lead to data consistency problems. To avoid such situations a locking mechanism is provided: use p_shm_lock() before entering a critical section on the memory segment and p_shm_unlock() when leaving this section. The locking mechanism is working across the process boundary.

A process-wide shared memory segment is identified by its name across the system, thus it is also called a named memory segment. Use p_shm_new() to open the named shared memory segment and p_shm_free() to close it.

Please note the following platform specific differences:

• Windows and OS/2 don't own IPC objects (processes own them), which means that a shared memory segment will be removed after the last process or thread detaches (or after terminating all the processes and threads attached to the segment) it.
• UNIX systems own IPC objects. Because of that UNIX IPC objects can survive an application crash: the attached shared memory segment can contain data from the previous working session. This could happen if you have not detached from all the shared memory segments explicitly before terminating the application.
• HP-UX has limitations due to its MPAS/MGAS features, so you couldn't attach to the same memory segment twice from the same process.
• IRIX allows to open several instances of the same buffer within the single process, but it will close the object after the first close call from any of the threads within the process.
• OpenVMS (as of 8.4 release) has broken implementation of process-wide named semaphores which leads to the broken shared memory also.
• Syllable lacks support for process-wide named semaphores which leads to the absence of shared memory.
• BeOS lacks support for process-wide named semaphores which leads to the absence of shared memory.

You can take ownership of the shared memory segment with p_shm_take_ownership() to explicitly remove it from the system after closing.

Definition in file pshm.h.

Typedef Documentation

PShm

typedef struct PShm_ PShm

Shared memory opaque data structure.

Definition at line 106 of file pshm.h.

PShmAccessPerms

typedef enum PShmAccessPerms_ PShmAccessPerms

Enum with shared memory access permissions.

Enumeration Type Documentation

PShmAccessPerms_

enum PShmAccessPerms_

Enum with shared memory access permissions.

Enumerator
P_SHM_ACCESS_READONLY	Read-only access.
P_SHM_ACCESS_READWRITE	Read/write access.

Definition at line 100 of file pshm.h.

Function Documentation

p_shm_free()

P_LIB_API void p_shm_free

(

PShm *

shm

)

Frees PShm object.

Parameters

shm	PShm to free.

Since

0.0.1

It doesn't unlock a given shared memory segment, be careful to not to make a deadlock or a segfault while freeing the memory segment which is under usage.

p_shm_get_address()

P_LIB_API ppointer p_shm_get_address

(

const PShm *

shm

)

Gets a starting address of a PShm memory segment.

Parameters

shm	PShm to get the address for.

Returns

Pointer to the starting address in case of success, NULL otherwise.

Since

0.0.1

p_shm_get_size()

P_LIB_API psize p_shm_get_size

(

const PShm *

shm

)

Gets the size of a PShm memory segment.

Parameters

shm	PShm to get the size for.

Returns

Size of the given memory segment in case of success, 0 otherwise.

Since

0.0.1

Note that the returned size would be a slightly larger than specified during the p_shm_new() call due to service information stored inside.

p_shm_lock()

P_LIB_API pboolean p_shm_lock	(	PShm *	shm,
		PError **	error
	)

Locks PShm object for usage.

Parameters

	shm	PShm to lock.
[out]	error	Error report object, NULL to ignore.

Returns

TRUE in case of success, FALSE otherwise.

Since

0.0.1

If the object is already locked then the thread will be suspended until the object becomes unlocked.

p_shm_new()

P_LIB_API PShm* p_shm_new	(	const pchar *	name,
		psize	size,
		PShmAccessPerms	perms,
		PError **	error
	)

Creates a new PShm object.

Parameters

	name	Shared memory name.
	size	Size of the memory segment in bytes, can't be changed later.
	perms	Memory segment permissions, see PShmAccessPerms.
[out]	error	Error report object, NULL to ignore.

Returns

Pointer to a newly created PShm object in case of success, NULL otherwise.

Since

0.0.1

p_shm_take_ownership()

P_LIB_API void p_shm_take_ownership

(

PShm *

shm

)

Takes ownership of a shared memory segment.

Parameters

shm	Shared memory segment.

Since

0.0.1

If you take ownership of the shared memory object, p_shm_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 will be unlinked from the system. To do that, call p_shm_new() and check if its condition is normal (the segment size, the data). If not, take ownership of the shared memory object and remove it with the p_shm_free() call. After that, create it again.

p_shm_unlock()

P_LIB_API pboolean p_shm_unlock	(	PShm *	shm,
		PError **	error
	)

Unlocks PShm object.

Parameters

	shm	PShm to unlock.
[out]	error	Error report object, NULL to ignore.

Returns

TRUE in case of success, FALSE otherwise.

Since

0.0.1