The track parameter of multiprocessing.shared_memory.SharedMemory controls whether a shared-memory segment is registered with Python’s multiprocessing resource tracker. This setting matters whenever multiple processes open the same memory block, especially when those processes are launched independently rather than as children of one multiprocessing program.
A wrong choice can cause premature deletion, resource-leak warnings, or abandoned shared-memory objects. This guide explains track=True, track=False, ownership, close(), unlink(), platform differences, synchronization, testing, and production patterns.
Why shared memory is useful
Shared memory lets processes access the same bytes without repeatedly serializing and copying large objects. It is valuable for numerical arrays, image frames, caches, machine-learning pipelines, and low-latency services. One process creates a segment and other processes attach by name.
from multiprocessing import shared_memory
shm = shared_memory.SharedMemory(create=True, size=1024)
try:
shm.buf[:4] = b"PYTH"
finally:
shm.close()
shm.unlink()close() releases the local handle. unlink() removes the shared-memory name. On POSIX systems, existing handles may remain usable after unlinking, but new clients cannot attach. On Windows, the operating system removes the segment after all handles are closed.
What track changes
With track=True, the segment is registered with the multiprocessing resource tracker. If a process exits without cleaning up, the tracker can remove the resource. This is convenient when processes belong to one coordinated multiprocessing family.
With track=False, the segment is not registered by that process. Your application must explicitly decide which process owns cleanup. This is often the correct model for processes launched by different shells, supervisors, containers, web workers, or services.
Independent processes and premature cleanup
Suppose a producer is launched by systemd and a consumer is started from a command line. If both use their own resource tracker and attach with track=True, the first tracker to exit may unlink the segment even while the other application still needs it. Existing handles may survive on POSIX, but future clients will fail to open the name.
A safer architecture assigns one owner. The owner creates the memory and eventually calls unlink(). Independent clients attach with track=False and call only close().
from multiprocessing import shared_memory
shm = shared_memory.SharedMemory(
name="academify_data",
create=False,
track=False,
)
try:
payload = bytes(shm.buf[:128])
finally:
shm.close()The single-owner pattern
A robust owner creates the segment, publishes its name, writes a protocol header, coordinates readers, and unlinks only during final shutdown. The owner may keep track=True as a fallback while independent clients use track=False.
from multiprocessing import shared_memory
shm = shared_memory.SharedMemory(
name="python_cache",
create=True,
size=4096,
track=True,
)
try:
shm.buf[:8] = b"CACHE001"
input("Press Enter to stop")
finally:
shm.close()
shm.unlink()This pattern makes ownership visible and prevents every consumer from competing to delete the same resource.
Processes from one multiprocessing program
When workers are created with multiprocessing.Process, Pool, or related tools in the same application, track=True is usually reasonable. Even then, explicit cleanup remains important. Use try/finally, document ownership, and test abrupt termination.
Related Academify guides include Python multiprocessing, Python queue, Python mmap, and Python memoryview. Each tool has a different ownership and synchronization model.
close is not unlink
This distinction is essential. Every participant should call close() when it no longer needs its local handle. Only the designated owner should normally call unlink(). Calling unlink from arbitrary clients creates races and makes availability depend on shutdown order.
If an application supports owner failover, define how a replacement owner is elected. Use a lease, lock file, supervisor record, or another reliable coordination mechanism rather than guessing from the existence of a segment.
Windows behavior
On Windows, shared memory is deleted automatically when all handles are closed, so tracking behaves differently. Portable programs should still use a clear owner and avoid relying on behavior observed on only one platform. A design that appears correct on Windows may unlink too early on Linux when resource trackers are independent.
Buffer format and validation
Shared memory provides bytes, not a self-describing object. Store a small header containing a protocol version, payload length, state, and optional checksum. Validate all fields before reading.
import struct
version, length = struct.unpack_from("!II", shm.buf, 0)
if version != 1:
raise RuntimeError("Unsupported version")
if length > len(shm.buf) - 8:
raise ValueError("Invalid payload length")For arrays, you can combine the buffer with memoryview, struct, or NumPy. Always verify shape, dtype, byte order, and total size.
Synchronization is separate
The track parameter does not lock the buffer. It only changes resource tracking. Readers and writers still need locks, semaphores, events, queues, or a versioned protocol. A common pattern marks a record as “writing,” copies the payload, stores a checksum, and finally changes the state to “ready.”
Crash handling
Plan for producers that crash before unlinking, consumers that remain alive, and services that restart. On startup, do not delete an existing segment blindly. It may belong to a healthy instance. Use names containing an application namespace, environment, and instance identifier. Store owner identity and protocol version in the header.
Container deployments also require IPC namespace awareness. Two containers may not see the same segment unless configured to share the relevant namespace.
Testing strategy
Test different shutdown orders: owner first, client first, multiple clients, forced termination, and restart. Verify that new clients can attach while the owner is alive and cannot attach after intentional unlinking. Test on each supported operating system.
For authoritative details, consult the Python shared_memory documentation and the multiprocessing documentation.
Common mistakes
Frequent errors include letting every process call unlink(), using track=True in unrelated processes without understanding separate trackers, forgetting close(), omitting synchronization, trusting unvalidated lengths, and reusing fixed names across deployments.
Another mistake is treating resource tracking as a substitute for lifecycle design. The tracker is a safety net, not an ownership protocol.
Production checklist
Choose one owner. Select track based on process topology. Close every handle. Unlink only at the correct final point. Validate headers and sizes. Synchronize access. Monitor abandoned segments. Test crashes and restarts. Verify behavior on Linux, macOS, and Windows when they are supported.
Conclusion
The track parameter does not change how processes read and write shared bytes; it changes whether a process asks the multiprocessing resource tracker to participate in cleanup. Use track=True for a coordinated multiprocessing family. Use track=False for independent clients when an explicit owner manages removal. With clear ownership, correct close() and unlink() usage, synchronization, validation, and tests, shared memory becomes both fast and predictable.
