plibsys 0.0.5
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.
 
typedef struct PShm_ PShm
 Shared memory opaque data structure.
 

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.
 
P_LIB_API void p_shm_take_ownership (PShm *shm)
 Takes ownership of a shared memory segment.
 
P_LIB_API void p_shm_free (PShm *shm)
 Frees PShm object.
 
P_LIB_API pboolean p_shm_lock (PShm *shm, PError **error)
 Locks PShm object for usage.
 
P_LIB_API pboolean p_shm_unlock (PShm *shm, PError **error)
 Unlocks PShm object.
 
P_LIB_API ppointer p_shm_get_address (const PShm *shm)
 Gets a starting address of a PShm memory segment.
 
P_LIB_API psize p_shm_get_size (const PShm *shm)
 Gets the size of a PShm memory segment.
 

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.

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.


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
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