core.threading

Available when: CHIC_OS == builtin.OS.MacOs

__ThreadStart : struct {
    entry : ThreadFunc
    user_data : ^void
}

Available when: CHIC_OS == builtin.OS.Windows

__ThreadStart : struct {
    entry : ThreadFunc
    user_data : ^void
    return_value : ^void
    refs : i32
}

Available when: CHIC_OS == builtin.OS.Windows

WindowsThread : struct {
    handle : posix.Handle
    id : posix.DWORD
    start : ^__ThreadStart
}

Thread : struct {
    native_handle : ThreadNativeHandle = null
}

Lightweight cross-platform thread handle.

Notes:
  - The native handle is platform-owned and should be treated as opaque.
  - A non-null native_handle means the Thread currently represents a
    joinable or detachable native thread.

Mutex : struct {
    native_handle : MutexNativeHandle
    initialized : bool = false
}

Lightweight cross-platform mutex handle.

Notes:
  - Use the platform Mutex() constructor to initialize it before locking.
  - initialized tracks whether the native mutex has been created.

CondVar : struct {
    native_handle : CondVarNativeHandle
    initialized : bool = false
}

Lightweight cross-platform condition variable handle.

Notes:
  - Use the platform CondVar() constructor to initialize it before waiting or
    signaling.
  - A condition variable must be used together with a locked Mutex.
  - wait(mutex) atomically unlocks the mutex and puts the current thread to
    sleep. When the thread wakes, wait locks the mutex again before returning.
  - Always wait in a loop that checks shared state; wakeups can be spurious or
    another thread may consume the condition first.

Example:
  mutex := Mutex()
  cond := CondVar()
  ready := false

  // Waiting thread:
  mutex.lock()
  for (!ready) {
      cond.wait(&mutex)
  }
  mutex.unlock()

  // Signaling thread:
  mutex.lock()
  ready = true
  cond.signal()
  mutex.unlock()

Available when: CHIC_OS == builtin.OS.MacOs

Mutex : func() -> [Mutex, ThreadingStatus]

Available when: CHIC_OS == builtin.OS.Windows

Mutex : func() -> [Mutex, ThreadingStatus]

Thread : func(entry : ThreadFunc, data : ^void) -> [Thread, ThreadingStatus]

Creates and starts a new thread with the given entry point and user data.

Parameters:
  entry : ThreadFunc - function executed by the new thread.
  data  : ^void      - opaque pointer passed to entry.

Returns:
  [Thread, ThreadingStatus]
    - On success: the started Thread and ThreadingStatus.Ok.
    - On failure: an empty Thread and the platform start error.

Notes:
  - The returned thread should be joined or detached by the caller.
  - The data pointer must remain valid for as long as the thread may read it.

Thread : func() -> Thread

Creates an empty thread handle without starting a native thread.

Returns:
  Thread - handle whose native_handle is null.

Notes:
  - Use Thread.start to start it later.

get_current_thread : func() -> Thread

Returns a Thread handle representing the calling thread.

Returns:
  Thread - platform-specific handle for the current thread.

Notes:
  - This does not create a new thread.
  - Ownership semantics are platform-specific; do not destroy this as if it
    were created by Thread(entry, data).

yield : func()

Gives the scheduler a chance to run another ready thread.

start : func(self : ^Thread, entry : ThreadFunc, data : ^void) -> [bool, ThreadingStatus]

Starts this thread handle with the given entry point and user data.

Parameters:
  self  : ^Thread    - thread handle to initialize.
  entry : ThreadFunc - function executed by the new native thread.
  data  : ^void      - opaque pointer passed to entry.

Returns:
  [bool, ThreadingStatus]
    - true and ThreadingStatus.Ok when the native thread was started.
    - false and an error status when self is invalid or already started.

Notes:
  - A thread can only be started once.
  - The caller should join or detach the thread after a successful start.

join : func(self : ^Thread, ret_value : ^^void) -> ThreadingStatus

Waits for this thread to finish and optionally retrieves its return value.

Parameters:
  self      : ^Thread - thread to wait for.
  ret_value : ^^void  - optional output pointer for the thread result.

Returns:
  ThreadingStatus.Ok on success, or a platform join error.

Notes:
  - Joining consumes the native handle; the Thread becomes invalid for
    future join/detach operations.
  - ret_value may be null if the caller does not need the thread result.

is_valid : func(self : ^Thread) -> bool

Returns true when this handle currently represents a native thread.

detach : func(self : ^Thread) -> ThreadingStatus

Releases this thread handle without waiting for the thread to finish.

Returns:
  ThreadingStatus.Ok on success, or a platform detach error.

Notes:
  - Detaching consumes the native handle; the Thread becomes invalid for
    future join/detach operations.
  - The detached thread continues running independently.

exit : func(self : ^Thread, ret_value : RawPtr)

Exits the current running thread with an optional raw return value.

Parameters:
  self      : ^Thread - unused receiver; the current thread exits.
  ret_value : RawPtr  - value made available to a joining thread.

Returns:
  This function does not return on platforms where thread exit succeeds.

Notes:
  - The value should be null or point to memory that remains valid after
    this thread exits.
  - This exits the calling thread, not an arbitrary thread represented by
    self.

destroy : func(self : ^Mutex) -> ThreadingStatus

Releases the native mutex resources.

Returns:
  ThreadingStatus.Ok on success, or a platform destroy error.

lock : func(self : ^Mutex) -> ThreadingStatus

Blocks until the mutex is acquired.

Returns:
  ThreadingStatus.Ok on success, or a platform lock error.

try_lock : func(self : ^Mutex) -> ThreadingStatus

Attempts to acquire the mutex without blocking.

Returns:
  ThreadingStatus.Ok when acquired, or ThreadingStatus.TryLockFailed when
  the mutex could not be acquired immediately.

unlock : func(self : ^Mutex) -> ThreadingStatus

Releases a mutex previously acquired by this thread.

Returns:
  ThreadingStatus.Ok on success, or a platform unlock error.

CondVar : func() -> CondVar

Creates a condition variable and returns the handle directly.

Returns:
  CondVar - initialized on success, empty on failure.

CondVar : func(status : ^ThreadingStatus) -> CondVar

Creates a condition variable and returns the handle directly.

Parameters:
  status : ^ThreadingStatus - optional output for initialization status.

Returns:
  CondVar - initialized on success, empty on failure.

destroy : func(self : ^CondVar) -> ThreadingStatus

Releases the native condition variable resources.

Returns:
  ThreadingStatus.Ok on success, or a platform destroy error.

wait : func(self : ^CondVar, mutex : ^Mutex) -> ThreadingStatus

Atomically releases the mutex and waits until this condition variable is
signaled, then reacquires the mutex before returning.

Returns:
  ThreadingStatus.Ok on success, or a platform wait error.

Notes:
  - The mutex must be locked by the calling thread before wait is called.
  - Callers should re-check their predicate after wait returns.

signal : func(self : ^CondVar) -> ThreadingStatus

Wakes one thread waiting on this condition variable.

Returns:
  ThreadingStatus.Ok on success, or a platform signal error.

broadcast : func(self : ^CondVar) -> ThreadingStatus

Wakes all threads waiting on this condition variable.

Returns:
  ThreadingStatus.Ok on success, or a platform broadcast error.