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

Link to this function

add_guard(shm)

View Source
add_guard(Shmex.t()) :: {:ok, Shmex.t()} | {:error, :already_guarded}

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

Link to this function

allocate(shm)

View Source
allocate(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

Link to this function

append(target, source)

View Source
append(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.

Link to this function

ensure_not_gc(shm)

View Source
ensure_not_gc(Shmex.t()) :: :ok

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.

Link to this function

read(shm)

View Source
read(Shmex.t()) ::
  {:ok, binary()} | {:error, {:file.posix(), :shm_open | :mmap}}

Reads the contents of shared memory and returns it as a binary.

Link to this function

read(shm, read_size)

View Source
read(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

Link to this function

set_capacity(shm, capacity)

View Source
set_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.

Link to this function

split_at(shm, position)

View Source
split_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.

Link to this function

trim(shm)

View Source
trim(Shmex.t()) ::
  {:ok, Shmex.t()} | {:error, {:file.posix(), :shm_open | :ftruncate}}

Trims shared memory capacity to match its size.

Link to this function

trim(shm, bytes)

View Source
trim(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.

Link to this function

write(shm, data)

View Source
write(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.