StormByte 3.0.0
C++26 foundation of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Safe::Detail Namespace Reference

Private helpers. More...

Classes

class  Owner
 Opaque unique state and creator-module lifetime callbacks. More...
struct  Control
 Base-owned reference counts and the real destructor. More...
struct  IsVoidFunction
 Whether T is a void-returning Function. More...
struct  IsVoidFunction< Function< void(Args...)> >
 A void-returning Function. More...
struct  ThreadState
 Decayed callable and arguments, allocated on Base's heap. More...
struct  FunctionState
 Function and its arguments, allocated on Base's heap. More...

Concepts

concept  SafeCallbackArgument
 Callback arguments admitted across a DLL boundary.
concept  SafeOptionalResult
 Recognizes a monadic result that can report an empty state.

Functions

void * WordCreate (std::size_t bytes)
 Allocate a zeroed word on Base's heap.
void WordDestroy (void *word) noexcept
 Destroy a word from WordCreate.
void WordLoad (void *word, std::size_t bytes, void *out, MemoryOrder order) noexcept
 Load the low bytes of a word.
void WordStore (void *word, std::size_t bytes, const void *value, MemoryOrder order) noexcept
 Store bytes into the low part of a word.
void WordExchange (void *word, std::size_t bytes, const void *desired, void *previous, MemoryOrder order) noexcept
 Replace the value and return the previous one.
bool WordCompareExchange (void *word, std::size_t bytes, void *expected, const void *desired, MemoryOrder success, MemoryOrder failure, bool weak) noexcept
 Compare-exchange the low bytes.
void WordFetchOp (void *word, std::size_t bytes, std::int64_t delta, void *previous, MemoryOrder order, int op) noexcept
 Integer operation on the low bytes.
void WordWait (void *word, std::size_t bytes, const void *old, MemoryOrder order) noexcept
 Wait while the low bytes still equal old.
void WordNotifyOne (void *word) noexcept
 Wake one waiter on word.
void WordNotifyAll (void *word) noexcept
 Wake every waiter on word.
bool WordLockFree (void *word) noexcept
 Whether Base's word is lock-free.
void ThrowSafeConversionFailure (const char *message)
 Throw Base's exception for a failed Safe conversion.
void * ThreadStart (void(*entry)(void *), void *argument)
 Start a thread whose body lives in Base.
void ThreadDestroy (void *thread) noexcept
 Destroy a thread from ThreadStart.
bool ThreadJoinable (void *thread) noexcept
 Whether the thread still owns an execution.
void ThreadJoin (void *thread)
 Wait until the execution returns.
void ThreadDetach (void *thread)
 Detach the execution.
std::uint64_t ThreadId (void *thread) noexcept
 Identifier of the owned execution.
std::uintptr_t ThreadNative (void *thread) noexcept
 Native handle as an integer.
std::uint64_t ThreadSelf () noexcept
 Identifier of the calling execution.
unsigned ThreadHardware () noexcept
 Hint of concurrent executions.
void ThreadYield () noexcept
 Offer the calling execution.
void ThreadSleep (std::uint64_t nanoseconds) noexcept
 Sleep the calling execution.

Detailed Description

Private helpers.

Control block shared by Shared and Weak.

Private implementation helpers for Safe containers.

Private implementation helpers for Safe callbacks.

Not a supported API.

Function Documentation

◆ ThreadDestroy()

void StormByte::Safe::Detail::ThreadDestroy ( void * thread)
noexcept

Destroy a thread from ThreadStart.

Parameters
threadThread address. A joinable thread terminates the process. Null is ignored.

◆ ThreadDetach()

void StormByte::Safe::Detail::ThreadDetach ( void * thread)

Detach the execution.

Parameters
threadThread address. Not null. Must be joinable.
Exceptions
ExceptionThe thread is not joinable.

◆ ThreadHardware()

unsigned StormByte::Safe::Detail::ThreadHardware ( )
noexcept

Hint of concurrent executions.

Returns
Zero when the hint is not available.

◆ ThreadId()

std::uint64_t StormByte::Safe::Detail::ThreadId ( void * thread)
noexcept

Identifier of the owned execution.

Parameters
threadThread address. Not null.
Returns
Zero when the object is not joinable.

◆ ThreadJoin()

void StormByte::Safe::Detail::ThreadJoin ( void * thread)

Wait until the execution returns.

Parameters
threadThread address. Not null. Must be joinable.
Exceptions
ExceptionThe thread is not joinable.

◆ ThreadJoinable()

bool StormByte::Safe::Detail::ThreadJoinable ( void * thread)
noexcept

Whether the thread still owns an execution.

Parameters
threadThread address. Not null.
Returns
Joinable flag.

◆ ThreadNative()

std::uintptr_t StormByte::Safe::Detail::ThreadNative ( void * thread)
noexcept

Native handle as an integer.

Not a CRT thread type.

Parameters
threadThread address. Not null.
Returns
Zero when the object is not joinable.

◆ ThreadSelf()

std::uint64_t StormByte::Safe::Detail::ThreadSelf ( )
noexcept

Identifier of the calling execution.

Returns
Non-zero identifier.

◆ ThreadSleep()

void StormByte::Safe::Detail::ThreadSleep ( std::uint64_t nanoseconds)
noexcept

Sleep the calling execution.

Parameters
nanosecondsDuration. Zero returns immediately.

◆ ThreadStart()

void * StormByte::Safe::Detail::ThreadStart ( void(* entry )(void *),
void * argument )

Start a thread whose body lives in Base.

Parameters
entryEntry. Not null. Base calls it and then returns.
argumentArgument passed to entry. May be null.
Returns
Base-owned thread. Never null.
Exceptions
AllocationErrorThe thread cannot be started.

◆ ThreadYield()

void StormByte::Safe::Detail::ThreadYield ( )
noexcept

Offer the calling execution.

◆ ThrowSafeConversionFailure()

void StormByte::Safe::Detail::ThrowSafeConversionFailure ( const char * message)

Throw Base's exception for a failed Safe conversion.

Parameters
messageFailure description.

◆ WordCompareExchange()

bool StormByte::Safe::Detail::WordCompareExchange ( void * word,
std::size_t bytes,
void * expected,
const void * desired,
MemoryOrder success,
MemoryOrder failure,
bool weak )
noexcept

Compare-exchange the low bytes.

Parameters
wordWord address.
bytesValue width.
expectedExpected value. Replaced with the actual value on failure.
desiredValue to store on success.
successOrder on success.
failureOrder on failure. Release and acq-rel are promoted to acquire.
weakWhether a spurious failure is allowed.
Returns
Whether the exchange happened.

◆ WordCreate()

void * StormByte::Safe::Detail::WordCreate ( std::size_t bytes)

Allocate a zeroed word on Base's heap.

Parameters
bytesWidth of the value. One, two, four or eight.
Returns
Base-owned word. Never null.
Exceptions
AllocationErrorThe word cannot be allocated.

◆ WordDestroy()

void StormByte::Safe::Detail::WordDestroy ( void * word)
noexcept

Destroy a word from WordCreate.

Parameters
wordWord address. Null is ignored.

◆ WordExchange()

void StormByte::Safe::Detail::WordExchange ( void * word,
std::size_t bytes,
const void * desired,
void * previous,
MemoryOrder order )
noexcept

Replace the value and return the previous one.

Parameters
wordWord address.
bytesValue width.
desiredNew value, bytes long.
previousDestination of the previous value.
orderOrder.

◆ WordFetchOp()

void StormByte::Safe::Detail::WordFetchOp ( void * word,
std::size_t bytes,
std::int64_t delta,
void * previous,
MemoryOrder order,
int op )
noexcept

Integer operation on the low bytes.

Parameters
wordWord address.
bytesValue width.
deltaOperand, already scaled for a pointer.
previousDestination of the previous value.
orderOrder.
opZero add, one subtract, two and, three or, four xor.

◆ WordLoad()

void StormByte::Safe::Detail::WordLoad ( void * word,
std::size_t bytes,
void * out,
MemoryOrder order )
noexcept

Load the low bytes of a word.

Parameters
wordWord address.
bytesValue width.
outDestination of bytes. Not null.
orderLoad order.

◆ WordLockFree()

bool StormByte::Safe::Detail::WordLockFree ( void * word)
noexcept

Whether Base's word is lock-free.

Parameters
wordWord address.
Returns
Lock-free flag of the Base word, not of the caller's std::atomic.

◆ WordNotifyAll()

void StormByte::Safe::Detail::WordNotifyAll ( void * word)
noexcept

Wake every waiter on word.

Parameters
wordWord address.

◆ WordNotifyOne()

void StormByte::Safe::Detail::WordNotifyOne ( void * word)
noexcept

Wake one waiter on word.

Parameters
wordWord address.

◆ WordStore()

void StormByte::Safe::Detail::WordStore ( void * word,
std::size_t bytes,
const void * value,
MemoryOrder order )
noexcept

Store bytes into the low part of a word.

Parameters
wordWord address.
bytesValue width.
valueSource of bytes. Not null.
orderStore order.

◆ WordWait()

void StormByte::Safe::Detail::WordWait ( void * word,
std::size_t bytes,
const void * old,
MemoryOrder order )
noexcept

Wait while the low bytes still equal old.

Parameters
wordWord address.
bytesValue width.
oldCaptured value.
orderLoad order used by the wait.