plibsys 0.0.5
|
Shared memory. More...
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 PShm * | p_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. | |
Shared memory.
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.
Definition in file pshm.h.
typedef struct PShm_ PShm |
enum PShmAccessPerms_ |
Gets the size of a PShm memory segment.
shm | PShm to get the size for. |
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_LIB_API PShm * p_shm_new | ( | const pchar * | name, |
psize | size, | ||
PShmAccessPerms | perms, | ||
PError ** | error ) |
Creates a new PShm object.
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. |
Takes ownership of a shared memory segment.
shm | Shared memory segment. |
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.