Shared Nodes
PBSharedNode
Opaque object handle: A named node that provides various methods through which applications and processes can communicate.
This object maintains an internal reference count. When the reference count reaches zero, the object will be automatically deallocated. To increment the reference count, call PBSharedNodeRetain; to decrement the reference count, call PBSharedNodeRelease. These functions are thread-safe.
PBSharedNodeOpenFlags
Enumeration/bitset of type uint32_t: Flags passed to PBSharedNode.
Constants
PBSharedNodeOpen_ALLOW_CREATION
PBSharedNodeOpen_ALLOW_CREATION = 1<<0
Create the node with the given name if it does not already exists. If the node already exists, this has no effect. If this flag is not set and the node does not already exist, the call to PBSharedNodeOpen will fail.
PBSharedNodeOpen
Function: Create or open a handle to a shared node.
Syntax (C/C++)
PBSharedNodePtr _Nullable PBSharedNodeOpen(ConstStr name,
PBSharedNodeOpenFlags flags);
Syntax (Python)
SharedNodeOpen(name, flags) -> (node)
Parameters and Return Values
[in] name (referenced string): The name of the shared node. This must be unique across the workspace. You are recommended to prefix this with your application's ID.
[in] flags (PBSharedNodeOpenFlags): A bitwise OR of flags determining how to open or create the node.
[out] node (nullable owned PBSharedNode): The handle to the shared node. You must be release this with PBSharedNodeRelease when you no longer need it. NULL is returned if the call fails.
Discussion
If PBSharedNodeOpen_ALLOW_CREATION is set in the flags, then this call can create nodes as well as open them.
Shared nodes are deleted once the last handle to them is closed. If a node is created with the same name later, then it will start with a blank state.
Even if the shared node is already open by the calling process, a new handle will be returned each time this function is called. It is therefore not possible to compare two shared nodes for equality by comparing their pointer values.
PBSharedNodeIncrementCounter
Function: Increment the counter of a shared node.
Syntax (C/C++)
uint64_t PBSharedNodeIncrementCounter(PBSharedNodeRef node);
Syntax (Python)
SharedNodeIncrementCounter(node) -> (previousValue)
Parameters and Return Values
[in] node (referenced PBSharedNode): The shared node. See PBSharedNodeOpen.
[out] previousValue (uint64_t): The previous value of the counter, before it is incremented.
Discussion
Every shared node has an internal 64-bit counter that starts at zero. By calling this function, the counter is incremented by one atomically. The previous value of the counter is returned. That is, the first time any process calls this function for a given shared node, zero is returned. The next call will return one, then two, and so on.
PBSharedNodeGetSocket
Function: Get the file descriptor for one socket in the node's socket pair.
Syntax (C/C++)
int32_t PBSharedNodeGetSocket(PBSharedNodeRef node, bool whichSocket);
Syntax (Python)
SharedNodeGetSocket(node, whichSocket) -> (socketFD)
Parameters and Return Values
[in] node (referenced PBSharedNode): The shared node. See PBSharedNodeOpen.
[in] whichSocket (bool): False for the first socket in the pair, or true for the second socket in the pair.
[out] socketFD (int32_t): The socket file descriptor. -1 is returned on failure.
Discussion
Every shared node has a socket pair associated with it. This function retrieves one of the sockets in the pair and returns a file descriptor that can be used in the calling process.
The socket file descriptor must be closed with close(2) when it is no longer needed.