plibsys
Typedefs | Enumerations | Functions
pshm.h File Reference

Shared memory. More...

#include <pmacros.h>
#include <ptypes.h>
#include <perror.h>
Include dependency graph for pshm.h:

Go to the source code of this file.

Typedefs

typedef P_BEGIN_DECLS 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 PShmp_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:

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

Typedef Documentation

◆ PShm

typedef struct PShm_ PShm

Shared memory opaque data structure.

◆ PShmAccessPerms

Enum with shared memory access permissions.

Enumeration Type Documentation

◆ PShmAccessPerms_

Enum with shared memory access permissions.

Enumerator
P_SHM_ACCESS_READONLY 

Read-only access.

P_SHM_ACCESS_READWRITE 

Read/write access.

Function Documentation

◆ p_shm_free()

P_LIB_API void p_shm_free ( PShm shm)

Frees PShm object.

Parameters
shmPShm 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
shmPShm 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
shmPShm 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
shmPShm to lock.
[out]errorError 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
nameShared memory name.
sizeSize of the memory segment in bytes, can't be changed later.
permsMemory segment permissions, see PShmAccessPerms.
[out]errorError 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
shmShared 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
shmPShm to unlock.
[out]errorError report object, NULL to ignore.
Returns
TRUE in case of success, FALSE otherwise.
Since
0.0.1