Capabilities and Objects

Runtime resources are objects (PBSysObjectType). Guest code accesses objects through handles which have rights (PBSysHandle, PBSysRights).

Handle model

• Handles are thread-local references to objects.
• Same object may be reachable through multiple handles with different rights.
• Handles can be duplicated (PBSysHandleDuplicate) with reduced rights.
• Handle id generation is used to detect stale/closed handle use.

Rights

Rights are bit flags attached to each handle. Examples:

• PBSysRight_READ / PBSysRight_WRITE
• PBSysRight_DUPLICATE / PBSysRight_TRANSFER
• PBSysRight_MANAGE_THREAD / PBSysRight_MANAGE_PROCESS
• PBSysRight_NETWORK
• PBSysRight_OBSERVE / PBSysRight_SIGNAL

See PBSysRightsBits for a complete list

Signals and observation

Objects expose signal bits (PBSysSignals):

• system signal bits (low 24 bits), object-type specific,
• user signal bits (high 8 bits) managed by guest via PBSysObjectSignal.

Observation is configured with PBSysObjectObserve:

• default mode is level-triggered,
• PBSysObjectObserve_ONCE gives one-shot behavior,
• PBSysObjectObserve_ADD augments existing observed set.

Signal notifications are delivered as PBSysSignalEvent via PBSysEventPoll.

Handle transfer between threads

Thread messaging (PBSysThreadWrite / PBSysThreadRead) can transfer ownership of handles. Transferred handles move between thread handle tables and keep object identity.

PBSysThreadStart can also transfer an initial handle set to the new thread through PBSysThreadConfig.transferHandles.

Default handles for main thread

During main thread setup, runtime grants default capabilities including:

• self thread handle (PBSysHandle_SELF_THREAD),
• console stream handle,
• default clock handle,
• default main window handle (unless GUI disabled).

Exact availability can depend on startup flags and host platform.