/***
    Copyright (C) 2021 J Reece Wilson (a/k/a "Reece"). All rights reserved.

    File: Threading.hpp
    Date: 2021-6-9
    Author: Reece
***/
#pragma once

namespace Aurora::Threading
{
    struct IWaitable;

    /// Surrenders the current threads time-slice to the kernel, on supporting platforms.
    /// You shouldn't need nor desire this.
    AUKN_SYM void ContextYield();

    /// This is a special primitive that anybody can lock at any point, and should be done so before locking global primitives.
    /// 
    /// Intended use case: AU_LOCK_GLOBAL_GUARD(gMyGLobalResourceMutex) or AU_LOCK_GLOBAL_GUARD(gSingleton.mutex)
    /// 
    /// I'll let you in on a little secret: it's not special; it's just the read side of a read write lock, with some special invokation logic on the write side.
    /// One should always expect this to *read lock* to pass without blocking.
    /// Once a thread is demanding the forceful termination of another, the write side is acquired, and future * non-recursive read * acquisitions are rejected until the requested thread has terminated.
    /// As previously stated, this is intended for protecting the lock guard of global primitives. Why? Global primitives cannot be as easily recycled.
    /// You can always trash a memory heap / component db / etc and reset. The forceful shutting down of a subsystem is viable, especially if their heaps are isolated and their IO resources tracked under a watchdog.
    /// On the otherhand, it's quite difficult to wrangle force thread shutdown, for two and a half reasons: 
    ///      1)   POSIX APIs do not allow force terminate,
    ///      1.5) clang is broken - it doesnt allow us to catch ghetto gcc abi::__forced_unwind - not that other users cant clobber these to begin with, and
    ///      2)   global locks may never be released.
    /// 1. Isn't an issue for us.
    /// 2. For short global read or write operations, GetShutdownLock can be held to ensure force thread termination doesn't mess up future consumers of a global resource.
    AUKN_SYM IWaitable *GetShutdownReadLock();
}

#include "IWaitable.hpp"

#include "Waitables/Waitables.hpp"
#include "Primitives/Primitives.hpp"

#include "WaitFor.hpp"
#include "Sleep.hpp"
#include "WakeOnAddress.hpp"

#include "LockGuard.hpp"
#include "LockGuardTry.hpp"

#include "SpinTime.hpp"

#include "Threads/Threads.hpp"

#include "InitOnce.hpp"