Shmex v0.2.1 Shmex.Native View Source
This module provides natively implemented functions allowing low-level operations on Posix shared memory. Use with caution!
Link to this section Summary
Functions
Creates guard for existing shared memory.
Creates shared memory segment and adds a guard for it.
Concatenates two shared memory areas by appending the data from the second
at the end of the first one. Fails with {:error, {:einval, :ftruncate}}
if
OS does not support changing shared memory capacity.
Ensures that shared memory is not garbage collected at the point of executing this function.
Reads the contents of shared memory and returns it as a binary.
Reads cnt
bytes from the shared memory and returns it as a binary.
Sets the capacity of shared memory area and updates the Shmex struct accordingly.
Splits the contents of shared memory area into two by moving the data past the specified position into a new shared memory.
Trims shared memory capacity to match its size.
Drops bytes
bytes from the beggining of shared memory area and
trims it to match the new size.
Writes the binary into the shared memory.
Link to this section Functions
Creates guard for existing shared memory.
This function should be only used when Shmex
struct was created by
some other NIF and even though the SHM exists, it's guard field is set to nil
.
Trying to use it with SHM obtained via allocate/1
will result in error.
See also docs for allocate/1
allocate(shm)
View Sourceallocate(Shmex.t()) :: {:ok, Shmex.t()} | {:error, {:file.posix(), :ftruncate}}
Creates shared memory segment and adds a guard for it.
The guard associated with this memory segment is placed in returned
Shmex
struct. When the guard resource is deallocated by BEAM,
the shared memory is unlinked and will disappear from the system when last process
using it unmaps it
append(target, source)
View Sourceappend(target :: Shmex.t(), source :: Shmex.t()) :: {:ok, Shmex.t()} | {:error, {:file.posix(), :shm_open | :mmap | :ftruncate}}
Concatenates two shared memory areas by appending the data from the second
at the end of the first one. Fails with {:error, {:einval, :ftruncate}}
if
OS does not support changing shared memory capacity.
The first shared memory is a target that will contain data from both shared memory areas. Its capacity will be set to the sum of sizes of both shared memory areas. The second one, the source, will remain unmodified.
Ensures that shared memory is not garbage collected at the point of executing this function.
Useful when passing shared memory to other OS process, to prevent it from being garbage collected until received and mapped by that process.
read(shm)
View Sourceread(Shmex.t()) :: {:ok, binary()} | {:error, {:file.posix(), :shm_open | :mmap}}
Reads the contents of shared memory and returns it as a binary.
read(shm, read_size)
View Sourceread(Shmex.t(), read_size :: non_neg_integer()) :: {:ok, binary()} | {:error, :invalid_read_size | {:file.posix(), :shm_open | :mmap}}
Reads cnt
bytes from the shared memory and returns it as a binary.
cnt
should not be greater than shm.size
set_capacity(shm, capacity)
View Sourceset_capacity(Shmex.t(), capacity :: pos_integer()) :: {:ok, Shmex.t()} | {:error, {:file.posix(), :shm_open | :ftruncate}}
Sets the capacity of shared memory area and updates the Shmex struct accordingly.
split_at(shm, position)
View Sourcesplit_at(Shmex.t(), position :: non_neg_integer()) :: {:ok, {Shmex.t(), Shmex.t()}} | {:error, {:file.posix(), :shm_open | :mmap | :ftruncate}}
Splits the contents of shared memory area into two by moving the data past the specified position into a new shared memory.
shm
has to be an existing shared memory (obtained via allocate/1
).
It virtually trims the existing shared memory to position
bytes
by setting size
to position
(The actual data is still present)
and the overlapping data is copied into the new shared memory area.
trim(shm)
View Sourcetrim(Shmex.t()) :: {:ok, Shmex.t()} | {:error, {:file.posix(), :shm_open | :ftruncate}}
Trims shared memory capacity to match its size.
trim(shm, bytes)
View Sourcetrim(Shmex.t(), bytes :: non_neg_integer()) :: {:ok, Shmex.t()} | {:error, {:file.posix(), :shm_open | :mmap}}
Drops bytes
bytes from the beggining of shared memory area and
trims it to match the new size.
write(shm, data)
View Sourcewrite(Shmex.t(), data :: binary()) :: {:ok, Shmex.t()} | {:error, {:file.posix(), :shm_open | :mmap}}
Writes the binary into the shared memory.
Overwrites the existing content. Increases the capacity of shared memory to fit the data.