slambb_smartbow_locations/Libraries/external/baselib/Include/C/Baselib_FileIO.h

#pragma once

// Baselib FileIO
//
// This is a file reading abstraction api heavily influenced by next-gen async API's like io_uring, windows register I/O, etc.
// This api allows for platform independent async file reading.

#include "Baselib_ErrorState.h"
#include "Baselib_Memory.h"
#include "Internal/Baselib_EnumSizeCheck.h"

#ifdef __cplusplus
BASELIB_C_INTERFACE
{
#endif

// Event queue handle.
typedef struct Baselib_FileIO_EventQueue {void* handle;} Baselib_FileIO_EventQueue;

// Async file handle.
typedef struct Baselib_FileIO_AsyncFile {void* handle;} Baselib_FileIO_AsyncFile;

// Sync file handle.
typedef struct Baselib_FileIO_SyncFile {void* handle;} Baselib_FileIO_SyncFile;

// Event queue handle invalid constant.
static const Baselib_FileIO_EventQueue Baselib_FileIO_EventQueue_Invalid = { NULL };

// Async file handle invalid constant.
static const Baselib_FileIO_AsyncFile Baselib_FileIO_AsyncFile_Invalid = { NULL };

// Sync file handle invalid constant.
static const Baselib_FileIO_SyncFile Baselib_FileIO_SyncFile_Invalid = { (void*)-1 };

typedef enum Baselib_FileIO_OpenFlags_t
{
    // Allows read access to the file.
    Baselib_FileIO_OpenFlags_Read         = 0x01,
    // Allows write access to the file.
    Baselib_FileIO_OpenFlags_Write        = 0x02,
    // Opens existing file without changes or creates 0 size file if file doesn't exist.
    // On some platforms open will implicitly add write flag if required by native API's.
    Baselib_FileIO_OpenFlags_OpenAlways   = 0x04,
    // Always creates 0 size file.
    // On some platforms open will implicitly add write flag if required by native API's.
    Baselib_FileIO_OpenFlags_CreateAlways = 0x08,
} Baselib_FileIO_OpenFlags_t;
typedef uint32_t Baselib_FileIO_OpenFlags;

// File IO read request.
typedef struct Baselib_FileIO_ReadRequest
{
    // Offset in a file to read from.
    // If offset+size is pointing pass EOF, will read up to EOF bytes.
    // If offset is pointing pass EOF, will read 0 bytes.
    uint64_t offset;
    // Buffer to read to, must be available for duration of operation.
    void*    buffer;
    // Size of requested read.
    // If 0 is passed will read 0 bytes and raise no error.
    uint64_t size;
} Baselib_FileIO_ReadRequest;

// File IO priorities.
// First we process all requests with high priority, then with normal priority.
// There's no round-robin, and high priority can starve normal priority.
typedef enum Baselib_FileIO_Priority
{
    Baselib_FileIO_Priority_Normal = 0,
    Baselib_FileIO_Priority_High   = 1
} Baselib_FileIO_Priority;
BASELIB_ENUM_ENSURE_ABI_COMPATIBILITY(Baselib_FileIO_Priority);

typedef enum Baselib_FileIO_EventQueue_ResultType
{
    // Upon receiving this event, please call the provided callback with provided data argument.
    Baselib_FileIO_EventQueue_Callback     = 1,
    // Result of open file operation.
    Baselib_FileIO_EventQueue_OpenFile     = 2,
    // Result of read file operation.
    Baselib_FileIO_EventQueue_ReadFile     = 3,
    // Result of close file operation.
    Baselib_FileIO_EventQueue_CloseFile    = 4
} Baselib_FileIO_EventQueue_ResultType;
BASELIB_ENUM_ENSURE_ABI_COMPATIBILITY(Baselib_FileIO_EventQueue_ResultType);

typedef void (*EventQueueCallback)(uint64_t userdata);

typedef struct Baselib_FileIO_EventQueue_Result_Callback
{
    // Please invoke this callback with userdata from the event.
    EventQueueCallback callback;
} Baselib_FileIO_EventQueue_Result_Callback;

typedef struct Baselib_FileIO_EventQueue_Result_OpenFile
{
    // Size of the file as seen on during open.
    uint64_t fileSize;
} Baselib_FileIO_EventQueue_Result_OpenFile;

typedef struct Baselib_FileIO_EventQueue_Result_ReadFile
{
    // Bytes transferred during read.
    uint64_t bytesTransferred;
} Baselib_FileIO_EventQueue_Result_ReadFile;

// Event queue result.
typedef struct Baselib_FileIO_EventQueue_Result
{
    // Event type.
    Baselib_FileIO_EventQueue_ResultType type;
    // Userdata as provided to the request.
    uint64_t                             userdata;
    // Error state of the operation.
    Baselib_ErrorState                   errorState;
    union
    {
        Baselib_FileIO_EventQueue_Result_Callback callback;
        Baselib_FileIO_EventQueue_Result_OpenFile openFile;
        Baselib_FileIO_EventQueue_Result_ReadFile readFile;
    };
} Baselib_FileIO_EventQueue_Result;

// Creates event queue.
//
// \returns Event queue.
BASELIB_API Baselib_FileIO_EventQueue Baselib_FileIO_EventQueue_Create(void);

// Frees event queue.
//
// \param eq event queue to free.
BASELIB_API void Baselib_FileIO_EventQueue_Free(
    Baselib_FileIO_EventQueue eq
);

// Dequeue events from event queue.
//
// \param                    eq Event queue to dequeue from.
// \param               results Results array to dequeue elements into.
//                              If null will return 0.
// \param                 count Amount of elements in results array.
//                              If equals 0 will return 0.
// \param timeoutInMilliseconds If no elements are present in the queue,
//                              waits for any elements to be appear for specified amount of time.
//                              If 0 is passed, wait is omitted.
//                              If elements are present, dequeues up-to-count elements, and wait is omitted.
//
// File operations errors are reported via Baselib_FileIO_EventQueue_Result::errorState
// Possible error codes:
// - InvalidPathname:             Requested pathname is invalid (not found, a directory, etc).
// - RequestedAccessIsNotAllowed: Access to requested pathname is not allowed.
// - IOError:                     IO error occured.
//
// \returns Amount of results filled.
BASELIB_API uint64_t Baselib_FileIO_EventQueue_Dequeue(
    Baselib_FileIO_EventQueue        eq,
    Baselib_FileIO_EventQueue_Result results[],
    uint64_t                         count,
    uint32_t                         timeoutInMilliseconds // 0 will return immediately
);

// Asynchronously opens a file.
//
// \param       eq Event queue to associate file with.
//                 File can only be associated with one event queue,
//                 but one event queue can be associated with multiple files.
//                 If invalid event queue is passed, will return invalid file handle.
// \param pathname Platform defined pathname of a file.
//                 Can be freed after this function returns.
//                 If null is passed will return invalid file handle.
// \param userdata Userdata to be set in the completion event.
// \param priority Priority for file opening operation.
//
// Please note errors are reported via Baselib_FileIO_EventQueue_Result::errorState
// Possible error codes:
// - InvalidPathname:             Requested pathname is invalid (not found, a directory, etc).
// - RequestedAccessIsNotAllowed: Access to requested pathname is not allowed.
// - IOError:                     IO error occured.
//
// \returns Async file handle, which can be used immediately for scheduling other operations.
//          In case if file opening fails, all scheduled operations will fail as well.
//          In case if invalid arguments are passed, might return invalid file handle (see args descriptions).
BASELIB_API Baselib_FileIO_AsyncFile Baselib_FileIO_AsyncOpen(
    Baselib_FileIO_EventQueue eq,
    const char*               pathname,
    uint64_t                  userdata,
    Baselib_FileIO_Priority   priority
);

// Asynchronously reads data from a file.
//
// Note scheduling reads on closed file is undefined.
//
// \param     file Async file to read from.
//                 If invalid file handle is passed, will no-op.
//                 If file handle was already closed, behavior is undefined.
// \param requests Requests to schedule.
//                 If more than 1 provided,
//                 will provide completion event per individual request in the array.
//                 If null is passed, will no-op.
// \param    count Amount of requests in requests array.
//                 If 0 is passed, will no-op.
// \param userdata Userdata to be set in the completion event(s).
// \param priority Priority for file reading operation(s).
//
// Please note errors are reported via Baselib_FileIO_EventQueue_Result::errorState
// If file is invalid handle, error can not be reported because event queue is not known.
// Possible error codes:
// - IOError:                     IO error occured.
BASELIB_API void Baselib_FileIO_AsyncRead(
    Baselib_FileIO_AsyncFile   file,
    Baselib_FileIO_ReadRequest requests[],
    uint64_t                   count,
    uint64_t                   userdata,
    Baselib_FileIO_Priority    priority
);

// Asynchronously closes a file.
//
// Will wait for all pending operations to complete,
// after that will close a file and put a completion event.
//
// \param file Async file to close.
//             If invalid file handle is passed, will no-op.
//
// Please note errors are reported via Baselib_FileIO_EventQueue_Result::errorState
// If file is invalid handle, error can not be reported because event queue is not known.
// Possible error codes:
// - IOError:                     IO error occured.
BASELIB_API void Baselib_FileIO_AsyncClose(
    Baselib_FileIO_AsyncFile file
);

// Synchronously opens a file.
//
// Will try use the most open access permissions options that are available for each platform.
// Meaning it might be possible for other process to write to file opened via this API.
// On most platforms file can be simultaneously opened with different open flags.
// If you require more strict options, or platform specific access configuration, please use Baselib_FileIO_SyncFileFromNativeHandle.
//
// \param pathname  Platform defined pathname to open.
// \param openFlags Open flags.
//                  If file is created because one of Create flags is passed, it will have size of 0 bytes.
//
// Possible error codes:
// - InvalidArgument:             Invalid argument was passed.
// - RequestedAccessIsNotAllowed: Request access is not allowed.
// - IOError:                     Generic IO error occured.
//
// \returns SyncFile handle.
BASELIB_API Baselib_FileIO_SyncFile Baselib_FileIO_SyncOpen(
    const char*                           pathname,
    Baselib_FileIO_OpenFlags              openFlags,
    Baselib_ErrorState*                   errorState
);

// Transfer ownership of native handle to Baselib_FileIO_SyncFile handle.
//
// This function transfers ownership, meaning you don't need to close native handle yourself,
// instead returned SyncFile must closed via Baselib_FileIO_SyncClose.
// Implementations might cache information about the file state,
// so native handle shouldn't be used after transfering ownership.
//
// \param handle Platform defined native handle.
//               If invalid native handle is passed, will return Baselib_FileIO_SyncFile_Invalid.
// \param type   Platform defined native handle type from Baselib_FileIO_NativeHandleType enum.
//               If unsupported type is passed, will return Baselib_FileIO_SyncFile_Invalid.
//
// \returns SyncFile handle.
BASELIB_API Baselib_FileIO_SyncFile Baselib_FileIO_SyncFileFromNativeHandle(
    uint64_t handle,
    uint32_t type
);

// Synchronously reads data from a file.
//
// \param file   File to read from.
//               If invalid file handle is passed, will raise InvalidArgument error and return 0.
// \param offset Offset in the file to read data at.
//               If offset+size goes past end-of-file (EOF), function will read until EOF.
//               If offset points past EOF, will return 0.
// \param buffer Pointer to data to read into.
// \param size   Size of data to read.
//
// Possible error codes:
// - InvalidArgument:            Invalid argument was passed.
// - IOError:                    Generic IO error occured.
//
// \returns Amount of bytes read.
BASELIB_API uint64_t Baselib_FileIO_SyncRead(
    Baselib_FileIO_SyncFile file,
    uint64_t                offset,
    void*                   buffer,
    uint64_t                size,
    Baselib_ErrorState*     errorState
);

// Synchronously writes data to a file.
//
// \param file   File to write to.
//               If invalid file handle is passed, will raise InvalidArgument error and return 0.
// \param offset Offset in the file to write data at.
//               If offset+size goes past end-of-file (EOF), then file will be resized.
// \param buffer Pointer to data to write.
// \param size   Size of data to write.
//
// Possible error codes:
// - InvalidArgument:            Invalid argument was passed.
// - IOError:                    Generic IO error occured.
//
// \returns Amount of bytes written.
BASELIB_API uint64_t Baselib_FileIO_SyncWrite(
    Baselib_FileIO_SyncFile file,
    uint64_t                offset,
    const void*             buffer,
    uint64_t                size,
    Baselib_ErrorState*     errorState
);

// Synchronously flushes file buffers.
//
// Operating system might buffer some write operations.
// Flushing buffers is required to guarantee (best effort) writing data to disk.
//
// \param file File to flush.
//             If invalid file handle is passed, will no-op.
//
// Possible error codes:
// - InvalidArgument:            Invalid argument was passed.
// - IOError:                    Generic IO error occured.
BASELIB_API void Baselib_FileIO_SyncFlush(
    Baselib_FileIO_SyncFile file,
    Baselib_ErrorState*     errorState
);

// Synchronously changes file size.
//
// \param file File to get size of.
//             If invalid file handle is passed, will raise invalid argument error.
// \param size New file size.
//
// Possible error codes:
// - InvalidArgument:            Invalid argument was passed.
// - IOError:                    Generic IO error occured.
//
// \returns File size.
BASELIB_API void Baselib_FileIO_SyncSetFileSize(
    Baselib_FileIO_SyncFile file,
    uint64_t                size,
    Baselib_ErrorState*     errorState
);

// Synchronously retrieves file size.
//
// \param file File to get size of.
//             If invalid file handle is passed, will return 0.
//
// Possible error codes:
// - InvalidArgument:            Invalid argument was passed.
// - IOError:                    Generic IO error occured.
//
// \returns File size.
BASELIB_API uint64_t Baselib_FileIO_SyncGetFileSize(
    Baselib_FileIO_SyncFile file,
    Baselib_ErrorState*     errorState
);

// Synchronously closes a file.
//
// Close does not guarantee that the data was written to disk,
// Please use Baselib_FileIO_SyncFlush to guarantee (best effort) that data was written to disk.
//
// \param file File to close.
//             If invalid file handle is passed, will no-op.
//
// Possible error codes:
// - InvalidArgument:            Invalid argument was passed.
// - IOError:                    Generic IO error occured.
BASELIB_API void Baselib_FileIO_SyncClose(
    Baselib_FileIO_SyncFile file,
    Baselib_ErrorState*     errorState
);

#include <C/Baselib_FileIO.inl.h>

#ifdef __cplusplus
} // BASELIB_C_INTERFACE
#endif