Skip to main content
The creator owns the region’s name. Each handle owns its mapping. Closing the creator removes the name; existing mappings stay usable until their handles close.

​
Create

SharedRegion::create calls shm_open with O_CREAT | O_EXCL | O_RDWR, sets the size with ftruncate, and maps the object with MAP_SHARED. Permissions are 0600, subject to the process umask. A duplicate name returns AlreadyExists. The first page holds a 64-byte header and padding. Data starts at the next page boundary. Capacity must be positive and a multiple of the system page size. Use the platform’s page size rather than assuming 4096 bytes; Apple Silicon macOS commonly uses 16384 bytes. Names contain only ASCII letters, digits, underscores, and hyphens. Zinc adds /zinc_ internally. The maximum user name is 25 bytes on macOS and 250 on Linux. The core initializes the header, then publishes its magic number with a release store. Failed creation removes the new name and releases the descriptor and mapping.

​
Open

SharedRegion::open opens the object, checks its size with fstat, and maps it. It acquires the published magic number before reading the immutable header fields. The version and capacity must match the library and the mapped size. Invalid, truncated, or incomplete regions return CorruptedRegion and release the mapping. An open racing with creation may find an incomplete region. Arrange for the creator to announce readiness before readers attach, or retry after that announcement. Each successful open increments the atomic handle count. The count is diagnostic; it does not control name removal or recover after process crashes.

​
Close

Dropping a Rust SharedRegion, or closing an adapter handle, decrements the count and unmaps that handle’s memory. Closing the creator also calls shm_unlink, regardless of the number of readers. After the creator closes:
  • New opens return NotFound.
  • Existing readers keep their mappings and can still access the data.
  • A new creator can reuse the name for a separate region. Old readers continue to see the old region.
Raw pointers and borrowed views must not be used after their owning mapping closes. Node buffers and Python views retain their mappings until garbage collection. Python close() releases the handle’s ownership, but exported views can defer name removal.

​
Shutdown and crashes

For graceful shutdown, write a shutdown flag using your application’s synchronization protocol, notify readers, then close the creator. Readers can finish using their mappings without leaving a stale name. If the creator crashes without dropping its handle, the name may remain. Reference counts are not repaired by the operating system. Confirm that the region is stale before removing it with shm_unlink("/zinc_<name>"); removing a live name can split users between different regions. On Linux, named regions appear under /dev/shm/zinc_<name>. macOS POSIX shared memory names do not appear as files. vmmap <pid> can help inspect a process’s mappings; ipcs lists System V IPC, not these POSIX objects.

​
Data lifetime

Zinc provides volatile shared memory, not durable storage. Notification orders memory access but does not flush data to disk. There is no guarantee that data survives a crash or reboot. See the error codes reference for return values.