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

    File: Primitives.hpp
    Date: 2022-4-14
    Author: Reece
***/
#pragma once

namespace Aurora::IO::IPC
{
    /**
     * @brief Inherits the standard ILoopSource-based event.
     *
     *  [*] Option: IPC auto-reset
     *  [*] Option: IPC manual reset
     *  [*] Lock-to-unlock semantics. Where to ::Lock() means to lock/wait for the IO resource,
     *      performing the atomic "unlocking" operation.
     *  [*] Can be ::Reset()
     *  [*] Unlock from any process via ::Set()
     * 
     *        Exposes a string handle via the IExportableIPC interface to be used with
     *         the ImportEvent function in any process in the users' resource namespace
     *         (Windows Object Namespace: Local\, Linux: namespace, bsd: jail).
     *
    */
    struct IPCEvent : Loop::ILSEvent, IExportableIPC
    {
    };

    /**
     * @brief Inherits the standard ILoopSource-based semaphore. 
     * 
     *        Exposes a string handle via the IExportableIPC interface to be used with 
     *         the ImportSemaphore function in any process in the users' resource
     *         namespace (Windows Object Namespace: Local\, Linux: namespace, bsd: jail).
     * 
    */
    struct IPCSemaphore : Loop::ILSSemaphore, IExportableIPC
    {
    };
    
    /**
     * @brief Inherits the standard ILoopSource-based mutex.
     *
     *  [*] IPC Mutex maintains identical behaviour to Win32s named mutex
     *  [*] One-time signalable to indicate lock ownership
     *  [*] TryLock = Try Acquire. No Yield.
     *  [*] Can be IPC safe between processes (unlock on crash)
     * 
     *  On Process termination, the IPC Mutex is unlocked (if owned by the process)
     * 
     * @warning Linux does not *natively* support such signaling. 
     *          
     *          Process lost is determined by a watchdog on the IPC server-side (not kernel).
     *          To recieve a lost signal in the case of pipes, or to be able to reacquire a
     *          named mutex after a process crash; you are bound by a slow internal IO tick
     *          under the grug worker thread.
     * 
     *          This is still safer than eventfd and lighter than shared pthreads. Latterly
     *           pthreads does not support IO signaling. Neither does the linux kernel for that
     *           matter. 
     * 
    */
    struct IPCMutex : Loop::ILSMutex, IExportableIPC
    {
    };

    /**
     * @brief Requests a named IO event for use within the users' domain/namespace/jail
     * @return
    */
    AUKN_SYM AuSPtr<IPCEvent>     NewEvent(bool triggered, bool atomicRelease);

    /**
     * @brief 
     * @param handle from IExportableIPC::ExportToString()
     * @return 
    */
    AUKN_SYM AuSPtr<IPCEvent>     ImportEvent(const AuString &handle);

    /**
     * @brief Requests a named IO semaphore for use within the users' domain/namespace/jail
     * @return
    */
    AUKN_SYM AuSPtr<IPCSemaphore> NewSemaphore(int startingValue);

    /**
     * @brief
     * @param handle from IExportableIPC::ExportToString()
     * @return
    */
    AUKN_SYM AuSPtr<IPCSemaphore> ImportSemaphore(const AuString &handle);

    /**
     * @brief Requests a named IO mutex for use within the users' domain/namespace/jail
     * @return 
    */
    AUKN_SYM AuSPtr<IPCMutex>     NewMutex();

    /**
     * @brief
     * @param handle from IExportableIPC::ExportToString()
     * @return
    */
    AUKN_SYM AuSPtr<IPCMutex>     ImportMutex(const AuString &handle);
}