dxd - dynax driver framework 2.7.0d222
cross platform open source driver development framework
Loading...
Searching...
No Matches
dx::shared::reference Class Reference

cross-process, crash-safe named reference count More...

#include <dx_shared_reference.h>

Inheritance diagram for dx::shared::reference:
Collaboration diagram for dx::shared::reference:

Public Member Functions

 dx_catchall () reference &initialize(const std
 releases this hold
 dx_catchall_rethrow () virtual void free() noexcept
 operator const os_event () const noexcept
 operator os_event () noexcept
 operator::HANDLE () const noexcept
 reference ()=default
 reference ()=default
 reference (const std::string &name)
 reference (const std::string &name)

Public Attributes

bool joined {}
 true if initialize() found another holder already present, false if this was the first

Protected Attributes

::HANDLE process

Detailed Description

cross-process, crash-safe named reference count

Holding an instance signals "I am interested in the named resource" to every other process doing the same under the same name - no explicit acquire/release protocol beyond construction/release() is needed. Each holder keeps a shared (LOCK_SH) advisory lock open on a small marker file; the kernel unconditionally releases a process' flock()s when its last file descriptor to the file closes, termination/crash included - so unlike a value manually incremented/decremented in shared memory, this can never desync when a holder disappears without an orderly release() (dx::shared::memory inherits from this class for exactly that reason: release()'s own return value - "was this the last holder" - drives shm_unlink() on the last free(), replacing what used to be a separate, crash-unsafe mapped counter. Whether the shared memory is currently in use is answered separately, by a cheap shm_open-without-O_CREAT existence probe - joined is not involved in that anymore). The marker file itself is intentionally never unlinked - same as the named semaphores in shared::event - so a later reference under the same name simply reopens it; that costs nothing since flock()s are per-open-file-description, not per-path.

release() reports whether this was the last remaining holder, so the caller can decide whether it is now safe to erase whatever this name was guarding (e.g. a per-process preference store).

joined reports the opposite end of the same lifetime: whether this instance's own initialize() found another holder already present, or was the first. Constructing a throwaway instance and discarding it again (destructor/free()) right after reading joined therefore doubles as a non-destructive, repeatable "is anyone (else) currently interested in this name" probe, without disturbing any lasting holder.

Holding an instance signals "I am interested in the named resource" to every other process doing the same under the same name - no explicit acquire/release protocol beyond construction/release() is needed. The underlying named mutex is kept alive by Windows for as long as any process holds an open handle to it, and Windows unconditionally closes all of a process' handles on termination, crash included - so unlike a value manually incremented/decremented in shared memory, this can never desync when a holder disappears without an orderly release() (e.g. dx::service::client::_device's own per-application reference, whose release() return value gates whether that application's non-persistent device settings get erased on disconnect). dx::shared::memory (Windows) does NOT use this class at all - the underlying file mapping kernel object is itself already Windows' own crash-safe "is anyone still using this" primitive, kept alive exactly as long as any process holds a real, mapped handle to it, so a cheap existence probe (open the mapping by name, then immediately close) answers that question directly, with no separate reference count needed.

release() reports whether this was the last remaining holder, so the caller can decide whether it is now safe to erase whatever this name was guarding (e.g. a per-process registry-backed preference store).

joined reports the opposite end of the same lifetime: whether this instance's own initialize() found another holder already present, or was the first. Constructing a throwaway instance and discarding it again (destructor/free()) right after reading joined therefore doubles as a non-destructive, repeatable "is anyone (else) currently interested in this name" probe, without disturbing any lasting holder.

Constructor & Destructor Documentation

◆ reference() [1/4]

dx::shared::reference::reference ( )
default

◆ reference() [2/4]

dx::shared::reference::reference ( const std::string & name)
inline

◆ reference() [3/4]

dx::shared::reference::reference ( )
default

◆ reference() [4/4]

dx::shared::reference::reference ( const std::string & name)
inline
Here is the call graph for this function:

Member Function Documentation

◆ dx_catchall()

dx::shared::reference::dx_catchall ( ) const &
inline

releases this hold

Returns
true if this was the last holder of this name - i.e. no other process currently has it open, and cleanup guarded by this name is now safe
Here is the call graph for this function:

◆ dx_catchall_rethrow()

dx::resource< invalid_t >::dx_catchall_rethrow ( )
inlinenoexceptinherited

◆ operator const os_event()

dx::resource< invalid_t >::operator const os_event ( ) const
inlinenoexceptinherited

◆ operator os_event()

dx::resource< invalid_t >::operator os_event ( )
inlinenoexceptinherited

◆ operator::HANDLE()

dx::resource< invalid_t >::operator::HANDLE ( ) const
inlinenoexceptinherited

Member Data Documentation

◆ joined

bool dx::shared::reference::joined {}

true if initialize() found another holder already present, false if this was the first

◆ process

::HANDLE dx::resource< invalid_t >::process
protectedinherited

The documentation for this class was generated from the following files:

(c) copyright 2009 dynamic acoustics e.U. generated on

a closed source license may be obtained by requesting a written permission from dynamic acoustics e.U.
however - governmental use generally and military use especially is strictly prohibited though.