initial upload

src/os/core/linux/os_core_linux.h

@@ -0,0 +1,88 @@
+// Copyright (c) 2024 Epic Games Tools
+// Licensed under the MIT license (https://opensource.org/license/mit/)
+
+#ifndef LINUX_H
+#define LINUX_H
+
+////////////////////////////////
+//~ NOTE(allen): Get all these linux includes
+
+#include <stdlib.h>
+#include <sys/mman.h>
+#include <sys/types.h>
+#include <sys/stat.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <linux/limits.h>
+#include <time.h>
+#include <dirent.h>
+#include <pthread.h>
+#include <sys/syscall.h>
+#include <signal.h>
+#include <errno.h>
+#include <dlfcn.h>
+#include <sys/sysinfo.h>
+
+////////////////////////////////
+//~ NOTE(allen): File Iterator
+
+struct LNX_FileIter{
+  int fd;
+  DIR *dir;
+};
+StaticAssert(sizeof(Member(OS_FileIter, memory)) >= sizeof(LNX_FileIter), file_iter_memory_size);
+
+////////////////////////////////
+//~ NOTE(allen): Threading Entities
+
+enum LNX_EntityKind{
+  LNX_EntityKind_Null,
+  LNX_EntityKind_Thread,
+  LNX_EntityKind_Mutex,
+  LNX_EntityKind_ConditionVariable,
+};
+
+struct LNX_Entity{
+  LNX_Entity *next;
+  LNX_EntityKind kind;
+  volatile U32 reference_mask;
+  union{
+    struct{
+      OS_ThreadFunctionType *func;
+      void *ptr;
+      pthread_t handle;
+    } thread;
+    pthread_mutex_t mutex;
+    pthread_cond_t cond;
+  };
+};
+
+////////////////////////////////
+//~ NOTE(allen): Safe Call Chain
+
+struct LNX_SafeCallChain{
+  LNX_SafeCallChain *next;
+  OS_ThreadFunctionType *fail_handler;
+  void *ptr;
+};
+
+////////////////////////////////
+//~ NOTE(allen): Helpers
+
+internal B32 lnx_write_list_to_file_descriptor(int fd, String8List list);
+
+internal void lnx_date_time_from_tm(DateTime *out, struct tm *in, U32 msec);
+internal void lnx_tm_from_date_time(struct tm *out, DateTime *in);
+internal void lnx_dense_time_from_timespec(DenseTime *out, struct timespec *in);
+internal void lnx_file_properties_from_stat(FileProperties *out, struct stat *in);
+
+internal String8 lnx_string_from_signal(int signum);
+internal String8 lnx_string_from_errno(int error_number);
+
+internal LNX_Entity* lnx_alloc_entity(LNX_EntityKind kind);
+internal void lnx_free_entity(LNX_Entity *entity);
+internal void* lnx_thread_base(void *ptr);
+
+internal void lnx_safe_call_sig_handler(int);
+
+#endif //LINUX_H

src/os/core/os_core.c

@@ -0,0 +1,265 @@
+// Copyright (c) 2024 Epic Games Tools
+// Licensed under the MIT license (https://opensource.org/license/mit/)
+
+////////////////////////////////
+//~ rjf: Handle Type Functions (Helpers, Implemented Once)
+
+internal OS_Handle
+os_handle_zero(void)
+{
+  OS_Handle handle = {0};
+  return handle;
+}
+
+internal B32
+os_handle_match(OS_Handle a, OS_Handle b)
+{
+  return a.u64[0] == b.u64[0];
+}
+
+internal void
+os_handle_list_push(Arena *arena, OS_HandleList *handles, OS_Handle handle)
+{
+  OS_HandleNode *n = push_array(arena, OS_HandleNode, 1);
+  n->v = handle;
+  SLLQueuePush(handles->first, handles->last, n);
+  handles->count += 1;
+}
+
+internal OS_HandleArray
+os_handle_array_from_list(Arena *arena, OS_HandleList *list)
+{
+  OS_HandleArray result = {0};
+  result.count = list->count;
+  result.v = push_array_no_zero(arena, OS_Handle, result.count);
+  U64 idx = 0;
+  for(OS_HandleNode *n = list->first; n != 0; n = n->next, idx += 1)
+  {
+    result.v[idx] = n->v;
+  }
+  return result;
+}
+
+////////////////////////////////
+//~ rjf: System Path Helper (Helper, Implemented Once)
+
+internal String8
+os_string_from_system_path(Arena *arena, OS_SystemPath path)
+{
+  String8List strs = {0};
+  os_string_list_from_system_path(arena, path, &strs);
+  String8 result = str8_list_first(&strs);
+  return result;
+}
+
+////////////////////////////////
+//~ rjf: Command Line Argc/Argv Helper (Helper, Implemented Once)
+
+internal String8List
+os_string_list_from_argcv(Arena *arena, int argc, char **argv)
+{
+  String8List result = {0};
+  for(int i = 0; i < argc; i += 1)
+  {
+    String8 str = str8_cstring(argv[i]);
+    str8_list_push(arena, &result, str);
+  }
+  return result;
+}
+
+////////////////////////////////
+//~ rjf: Process Helpers (Helper, Implemented Once)
+
+internal void
+os_relaunch_self(void){
+  Temp scratch = scratch_begin(0, 0);
+  OS_LaunchOptions opts = {0};
+  opts.cmd_line = os_get_command_line_arguments();
+  opts.path = os_string_from_system_path(scratch.arena, OS_SystemPath_Initial);
+  os_launch_process(&opts, 0);
+  scratch_end(scratch);
+}
+
+////////////////////////////////
+//~ rjf: Filesystem Helpers (Helpers, Implemented Once)
+
+internal String8
+os_data_from_file_path(Arena *arena, String8 path)
+{
+  OS_Handle file = os_file_open(OS_AccessFlag_Read|OS_AccessFlag_Shared, path);
+  FileProperties props = os_properties_from_file(file);
+  String8 data = os_string_from_file_range(arena, file, r1u64(0, props.size));
+  os_file_close(file);
+  return data;
+}
+
+internal B32
+os_write_data_to_file_path(String8 path, String8 data)
+{
+  B32 good = 0;
+  OS_Handle file = os_file_open(OS_AccessFlag_Write, path);
+  if(!os_handle_match(file, os_handle_zero()))
+  {
+    good = 1;
+    os_file_write(file, r1u64(0, data.size), data.str);
+    os_file_close(file);
+  }
+  return good;
+}
+
+internal B32
+os_write_data_list_to_file_path(String8 path, String8List list)
+{
+  B32 good = 0;
+  OS_Handle file = os_file_open(OS_AccessFlag_Write, path);
+  if(!os_handle_match(file, os_handle_zero()))
+  {
+    good = 1;
+    U64 off = 0;
+    for(String8Node *n = list.first; n != 0; n = n->next)
+    {
+      os_file_write(file, r1u64(off, off+n->string.size), n->string.str);
+      off += n->string.size;
+    }
+    os_file_close(file);
+  }
+  return good;
+}
+
+internal FileProperties
+os_properties_from_file_path(String8 path)
+{
+  OS_Handle file = os_file_open(OS_AccessFlag_Read|OS_AccessFlag_Shared, path);
+  FileProperties props = os_properties_from_file(file);
+  os_file_close(file);
+  return props;
+}
+
+internal OS_FileID
+os_id_from_file_path(String8 path)
+{
+  OS_Handle file = os_file_open(OS_AccessFlag_Read|OS_AccessFlag_Shared, path);
+  OS_FileID id = os_id_from_file(file);
+  os_file_close(file);
+  return id;
+}
+
+internal S64
+os_file_id_compare(OS_FileID a, OS_FileID b)
+{
+  S64 cmp = MemoryCompare((void*)&a.v[0], (void*)&b.v[0], sizeof(a.v));
+  return cmp;
+}
+
+internal String8
+os_string_from_file_range(Arena *arena, OS_Handle file, Rng1U64 range)
+{
+  U64 pre_pos = arena_pos(arena);
+  String8 result;
+  result.size = dim_1u64(range);
+  result.str = push_array_no_zero(arena, U8, result.size);
+  U64 actual_read_size = os_file_read(file, range, result.str);
+  if(actual_read_size < result.size)
+  {
+    arena_pop_to(arena, pre_pos + actual_read_size);
+    result.size = actual_read_size;
+  }
+  return result;
+}
+
+////////////////////////////////
+//~ rjf: Synchronization Primitive Helpers (Helpers, Implemented Once)
+
+internal void
+os_mutex_take(OS_Handle mutex){
+  ProfBeginLockWait((void *)(mutex.u64[0]), "take mutex");
+  os_mutex_take_(mutex);
+  ProfEndLockWait();
+  ProfLockTake((void *)(mutex.u64[0]), "take mutex");
+}
+
+internal void
+os_mutex_drop(OS_Handle mutex){
+  os_mutex_drop_(mutex);
+  ProfLockDrop((void *)(mutex.u64[0]));
+}
+
+internal void
+os_rw_mutex_take_r(OS_Handle rw_mutex){
+  ProfBeginLockWait((void *)(rw_mutex.u64[0]), "rw mutex take r");
+  os_rw_mutex_take_r_(rw_mutex);
+  ProfEndLockWait();
+  ProfLockTake((void *)(rw_mutex.u64[0]), "rw mutex take r");
+}
+
+internal void
+os_rw_mutex_drop_r(OS_Handle rw_mutex){
+  os_rw_mutex_drop_r_(rw_mutex);
+  ProfLockDrop((void *)(rw_mutex.u64[0]));
+}
+
+internal void
+os_rw_mutex_take_w(OS_Handle rw_mutex){
+  ProfBeginLockWait((void *)(rw_mutex.u64[0]), "rw mutex take rw");
+  os_rw_mutex_take_w_(rw_mutex);
+  ProfEndLockWait();
+  ProfLockTake((void *)(rw_mutex.u64[0]), "rw mutex take rw");
+}
+
+internal void
+os_rw_mutex_drop_w(OS_Handle rw_mutex){
+  os_rw_mutex_drop_w_(rw_mutex);
+  ProfLockDrop((void *)(rw_mutex.u64[0]));
+}
+
+internal B32
+os_condition_variable_wait(OS_Handle cv, OS_Handle mutex, U64 endt_us){
+  ProfLockDrop((void *)(mutex.u64[0]));
+  B32 result = os_condition_variable_wait_(cv, mutex, endt_us);
+  ProfLockTake((void *)(mutex.u64[0]), "wait cv");
+  return(result);
+}
+
+internal B32
+os_condition_variable_wait_rw_r(OS_Handle cv, OS_Handle mutex_rw, U64 endt_us){
+  ProfLockDrop((void *)(mutex_rw.u64[0]));
+  B32 result = os_condition_variable_wait_rw_r_(cv, mutex_rw, endt_us);
+  ProfLockTake((void *)(mutex_rw.u64[0]), "wait cv rw r");
+  return(result);
+}
+
+internal B32
+os_condition_variable_wait_rw_w(OS_Handle cv, OS_Handle mutex_rw, U64 endt_us){
+  ProfLockDrop((void *)(mutex_rw.u64[0]));
+  B32 result = os_condition_variable_wait_rw_w_(cv, mutex_rw, endt_us);
+  ProfLockTake((void *)(mutex_rw.u64[0]), "wait cv rw w");
+  return(result);
+}
+
+internal void
+os_condition_variable_signal(OS_Handle cv){
+  os_condition_variable_signal_(cv);
+}
+
+internal void
+os_condition_variable_broadcast(OS_Handle cv){
+  os_condition_variable_broadcast_(cv);
+}
+
+internal String8
+os_string_from_guid(Arena *arena, OS_Guid guid)
+{
+  String8 result = push_str8f(arena, "%08X-%04X-%04X-%02X%02X-%02X%02X%02X%02X%02X%02X",
+                              guid.data1,
+                              guid.data2,
+                              guid.data3,
+                              guid.data4[0],
+                              guid.data4[1],
+                              guid.data4[2],
+                              guid.data4[3],
+                              guid.data4[4],
+                              guid.data4[5],
+                              guid.data4[6],
+                              guid.data4[7]);
+  return result;
+}

src/os/core/os_core.h

@@ -0,0 +1,365 @@
+// Copyright (c) 2024 Epic Games Tools
+// Licensed under the MIT license (https://opensource.org/license/mit/)
+
+#ifndef OS_CORE_H
+#define OS_CORE_H
+
+////////////////////////////////
+//~ rjf: Access Flags
+
+typedef U32 OS_AccessFlags;
+enum
+{
+  OS_AccessFlag_Read    = (1<<0),
+  OS_AccessFlag_Write   = (1<<1),
+  OS_AccessFlag_Execute = (1<<2),
+  OS_AccessFlag_Shared  = (1<<3),
+};
+
+////////////////////////////////
+//~ allen: Files
+
+typedef U32 OS_FileIterFlags;
+enum
+{
+  OS_FileIterFlag_SkipFolders     = (1 << 0),
+  OS_FileIterFlag_SkipFiles       = (1 << 1),
+  OS_FileIterFlag_SkipHiddenFiles = (1 << 2),
+  OS_FileIterFlag_Done            = (1 << 31),
+};
+
+typedef struct OS_FileIter OS_FileIter;
+struct OS_FileIter
+{
+  OS_FileIterFlags flags;
+  U8 memory[600];
+};
+
+typedef struct OS_FileInfo OS_FileInfo;
+struct OS_FileInfo
+{
+  String8 name;
+  FileProperties props;
+};
+
+// nick: on-disk file identifier
+typedef struct OS_FileID OS_FileID;
+struct OS_FileID
+{
+  U64 v[3];
+};
+
+////////////////////////////////
+//~ rjf: System Paths
+
+typedef enum OS_SystemPath
+{
+  OS_SystemPath_Binary,
+  OS_SystemPath_Initial,
+  OS_SystemPath_Current,
+  OS_SystemPath_UserProgramData,
+  OS_SystemPath_ModuleLoad,
+}
+OS_SystemPath;
+
+typedef enum OS_PathFromUserKind
+{
+  OS_PathFromUserKind_Save,
+  OS_PathFromUserKind_Load,
+}
+OS_PathFromUserKind;
+
+typedef struct OS_PathFromUser OS_PathFromUser;
+struct OS_PathFromUser
+{
+  OS_PathFromUserKind kind;
+  String8 path;
+  U64 filter_count;
+  String8 *filter_extensions;
+  String8 *filter_names;
+};
+
+////////////////////////////////
+//~ allen: Launch Input
+
+typedef struct OS_LaunchOptions OS_LaunchOptions;
+struct OS_LaunchOptions
+{
+  String8List cmd_line;
+  String8 path;
+  String8List env;
+  B32 inherit_env;
+  B32 consoleless;
+};
+
+////////////////////////////////
+//~ rjf: Handle Type
+
+typedef struct OS_Handle OS_Handle;
+struct OS_Handle
+{
+  U64 u64[1];
+};
+
+typedef struct OS_HandleNode OS_HandleNode;
+struct OS_HandleNode
+{
+  OS_HandleNode *next;
+  OS_Handle v;
+};
+
+typedef struct OS_HandleList OS_HandleList;
+struct OS_HandleList
+{
+  OS_HandleNode *first;
+  OS_HandleNode *last;
+  U64 count;
+};
+
+typedef struct OS_HandleArray OS_HandleArray;
+struct OS_HandleArray
+{
+  OS_Handle *v;
+  U64 count;
+};
+
+////////////////////////////////
+// Time
+
+#define OS_UNIX_TIME_MAX max_U32
+typedef U32 OS_UnixTime;
+
+////////////////////////////////
+// Global Unique ID
+
+typedef struct OS_Guid
+{
+  U32 data1;
+  U16 data2;
+  U16 data3;
+  U8  data4[8];
+} OS_Guid;
+StaticAssert(sizeof(OS_Guid) == 16, os_guid_check);
+
+////////////////////////////////
+//~ rjf: Thread Types
+
+typedef void OS_ThreadFunctionType(void *ptr);
+
+////////////////////////////////
+//~ rjf: Handle Type Functions (Helpers, Implemented Once)
+
+internal OS_Handle os_handle_zero(void);
+internal B32 os_handle_match(OS_Handle a, OS_Handle b);
+internal void os_handle_list_push(Arena *arena, OS_HandleList *handles, OS_Handle handle);
+internal OS_HandleArray os_handle_array_from_list(Arena *arena, OS_HandleList *list);
+
+////////////////////////////////
+//~ rjf: System Path Helper (Helper, Implemented Once)
+
+internal String8 os_string_from_system_path(Arena *arena, OS_SystemPath path);
+
+////////////////////////////////
+//~ rjf: Command Line Argc/Argv Helper (Helper, Implemented Once)
+
+internal String8List os_string_list_from_argcv(Arena *arena, int argc, char **argv);
+
+////////////////////////////////
+//~ rjf: Process Helpers (Helper, Implemented Once)
+
+internal void os_relaunch_self(void);
+
+////////////////////////////////
+//~ rjf: Filesystem Helpers (Helpers, Implemented Once)
+
+internal String8        os_data_from_file_path(Arena *arena, String8 path);
+internal B32            os_write_data_to_file_path(String8 path, String8 data);
+internal B32            os_write_data_list_to_file_path(String8 path, String8List list);
+internal FileProperties os_properties_from_file_path(String8 path);
+internal OS_FileID      os_id_from_file_path(String8 path);
+internal S64            os_file_id_compare(OS_FileID a, OS_FileID b);
+internal String8        os_string_from_file_range(Arena *arena, OS_Handle file, Rng1U64 range);
+
+////////////////////////////////
+//~ rjf: Synchronization Primitive Helpers (Helpers, Implemented Once)
+
+internal void os_mutex_take(OS_Handle mutex);
+internal void os_mutex_drop(OS_Handle mutex);
+internal void os_rw_mutex_take_r(OS_Handle rw_mutex);
+internal void os_rw_mutex_drop_r(OS_Handle rw_mutex);
+internal void os_rw_mutex_take_w(OS_Handle rw_mutex);
+internal void os_rw_mutex_drop_w(OS_Handle rw_mutex);
+// returns false on timeout, true on signal, (max_wait_ms = max_U64) -> no timeout
+internal B32  os_condition_variable_wait(OS_Handle cv, OS_Handle mutex, U64 endt_us);
+internal B32  os_condition_variable_wait_rw_r(OS_Handle cv, OS_Handle rw_mutex, U64 endt_us);
+internal B32  os_condition_variable_wait_rw_w(OS_Handle cv, OS_Handle rw_mutex, U64 endt_us);
+internal void os_condition_variable_signal(OS_Handle cv);
+internal void os_condition_variable_broadcast(OS_Handle cv);
+
+#define OS_MutexScope(mutex) DeferLoop(os_mutex_take(mutex), os_mutex_drop(mutex))
+#define OS_MutexScopeR(mutex) DeferLoop(os_rw_mutex_take_r(mutex), os_rw_mutex_drop_r(mutex))
+#define OS_MutexScopeW(mutex) DeferLoop(os_rw_mutex_take_w(mutex), os_rw_mutex_drop_w(mutex))
+
+////////////////////////////////
+//~ rjf: @os_hooks Main Initialization API (Implemented Per-OS)
+
+internal void os_init(int argc, char **argv);
+
+////////////////////////////////
+//~ rjf: @os_hooks Memory Allocation (Implemented Per-OS)
+
+internal void* os_reserve(U64 size);
+internal B32   os_commit(void *ptr, U64 size);
+internal void* os_reserve_large(U64 size);
+internal B32   os_commit_large(void *ptr, U64 size);
+internal void  os_decommit(void *ptr, U64 size);
+internal void  os_release(void *ptr, U64 size);
+
+internal B32 os_set_large_pages(B32 flag);
+internal B32 os_large_pages_enabled(void);
+internal U64 os_large_page_size(void);
+
+internal void* os_alloc_ring_buffer(U64 size, U64 *actual_size_out);
+internal void  os_free_ring_buffer(void *ring_buffer, U64 actual_size);
+
+////////////////////////////////
+//~ rjf: @os_hooks System Info (Implemented Per-OS)
+
+internal String8      os_machine_name(void);
+internal U64          os_page_size(void);
+internal U64          os_allocation_granularity(void);
+internal U64          os_logical_core_count(void);
+
+////////////////////////////////
+//~ rjf: @os_hooks Process Info (Implemented Per-OS)
+
+internal String8List os_get_command_line_arguments(void);
+internal S32         os_get_pid(void);
+internal S32         os_get_tid(void);
+internal String8List os_get_environment(void);
+internal U64         os_string_list_from_system_path(Arena *arena, OS_SystemPath path, String8List *out);
+
+////////////////////////////////
+//~ rjf: @os_hooks Process Control (Implemented Per-OS)
+
+internal void os_exit_process(S32 exit_code);
+
+////////////////////////////////
+//~ rjf: @os_hooks File System (Implemented Per-OS)
+
+//- rjf: files
+internal OS_Handle      os_file_open(OS_AccessFlags flags, String8 path);
+internal void           os_file_close(OS_Handle file);
+internal U64            os_file_read(OS_Handle file, Rng1U64 rng, void *out_data);
+internal void           os_file_write(OS_Handle file, Rng1U64 rng, void *data);
+internal B32            os_file_set_times(OS_Handle file, DateTime time);
+internal FileProperties os_properties_from_file(OS_Handle file);
+internal OS_FileID      os_id_from_file(OS_Handle file);
+internal B32            os_delete_file_at_path(String8 path);
+internal B32            os_copy_file_path(String8 dst, String8 src);
+internal String8        os_full_path_from_path(Arena *arena, String8 path);
+internal B32            os_file_path_exists(String8 path);
+
+//- rjf: file maps
+internal OS_Handle os_file_map_open(OS_AccessFlags flags, OS_Handle file);
+internal void      os_file_map_close(OS_Handle map);
+internal void *    os_file_map_view_open(OS_Handle map, OS_AccessFlags flags, Rng1U64 range);
+internal void      os_file_map_view_close(OS_Handle map, void *ptr);
+
+//- rjf: directory iteration
+internal OS_FileIter *os_file_iter_begin(Arena *arena, String8 path, OS_FileIterFlags flags);
+internal B32          os_file_iter_next(Arena *arena, OS_FileIter *iter, OS_FileInfo *info_out);
+internal void         os_file_iter_end(OS_FileIter *iter);
+
+//- rjf: directory creation
+internal B32 os_make_directory(String8 path);
+
+////////////////////////////////
+//~ rjf: @os_hooks Shared Memory (Implemented Per-OS)
+
+internal OS_Handle os_shared_memory_alloc(U64 size, String8 name);
+internal OS_Handle os_shared_memory_open(String8 name);
+internal void      os_shared_memory_close(OS_Handle handle);
+internal void *    os_shared_memory_view_open(OS_Handle handle, Rng1U64 range);
+internal void      os_shared_memory_view_close(OS_Handle handle, void *ptr);
+
+////////////////////////////////
+//~ rjf: @os_hooks Time (Implemented Per-OS)
+
+internal OS_UnixTime os_now_unix(void);
+internal DateTime    os_now_universal_time(void);
+internal DateTime    os_universal_time_from_local_time(DateTime *local_time);
+internal DateTime    os_local_time_from_universal_time(DateTime *universal_time);
+internal U64         os_now_microseconds(void);
+internal void        os_sleep_milliseconds(U32 msec);
+
+////////////////////////////////
+//~ rjf: @os_hooks Child Processes (Implemented Per-OS)
+
+internal B32   os_launch_process(OS_LaunchOptions *options, OS_Handle *handle_out);
+internal B32   os_process_wait(OS_Handle handle, U64 endt_us);
+internal void  os_process_release_handle(OS_Handle handle);
+
+////////////////////////////////
+//~ rjf: @os_hooks Threads (Implemented Per-OS)
+
+internal OS_Handle os_launch_thread(OS_ThreadFunctionType *func, void *ptr, void *params);
+internal void      os_release_thread_handle(OS_Handle thread);
+
+////////////////////////////////
+//~ rjf: @os_hooks Synchronization Primitives (Implemented Per-OS)
+
+// NOTE(allen): Mutexes are recursive - support counted acquire/release nesting
+// on a single thread
+
+//- rjf: recursive mutexes
+internal OS_Handle os_mutex_alloc(void);
+internal void      os_mutex_release(OS_Handle mutex);
+internal void      os_mutex_take_(OS_Handle mutex);
+internal void      os_mutex_drop_(OS_Handle mutex);
+
+//- rjf: reader/writer mutexes
+internal OS_Handle os_rw_mutex_alloc(void);
+internal void      os_rw_mutex_release(OS_Handle rw_mutex);
+internal void      os_rw_mutex_take_r_(OS_Handle mutex);
+internal void      os_rw_mutex_drop_r_(OS_Handle mutex);
+internal void      os_rw_mutex_take_w_(OS_Handle mutex);
+internal void      os_rw_mutex_drop_w_(OS_Handle mutex);
+
+//- rjf: condition variables
+internal OS_Handle os_condition_variable_alloc(void);
+internal void      os_condition_variable_release(OS_Handle cv);
+// returns false on timeout, true on signal, (max_wait_ms = max_U64) -> no timeout
+internal B32       os_condition_variable_wait_(OS_Handle cv, OS_Handle mutex, U64 endt_us);
+internal B32       os_condition_variable_wait_rw_r_(OS_Handle cv, OS_Handle mutex_rw, U64 endt_us);
+internal B32       os_condition_variable_wait_rw_w_(OS_Handle cv, OS_Handle mutex_rw, U64 endt_us);
+internal void      os_condition_variable_signal_(OS_Handle cv);
+internal void      os_condition_variable_broadcast_(OS_Handle cv);
+
+//- rjf: cross-process semaphores
+internal OS_Handle os_semaphore_alloc(U32 initial_count, U32 max_count, String8 name);
+internal void      os_semaphore_release(OS_Handle semaphore);
+internal OS_Handle os_semaphore_open(String8 name);
+internal void      os_semaphore_close(OS_Handle semaphore);
+internal B32       os_semaphore_take(OS_Handle semaphore, U64 endt_us);
+internal void      os_semaphore_drop(OS_Handle semaphore);
+
+////////////////////////////////
+//~ rjf: @os_hooks Dynamically-Loaded Libraries (Implemented Per-OS)
+
+internal OS_Handle os_library_open(String8 path);
+internal VoidProc *os_library_load_proc(OS_Handle lib, String8 name);
+internal void      os_library_close(OS_Handle lib);
+
+////////////////////////////////
+//~ rjf: @os_hooks Safe Calls (Implemented Per-OS)
+
+internal void os_safe_call(OS_ThreadFunctionType *func, OS_ThreadFunctionType *fail_handler, void *ptr);
+
+////////////////////////////////
+//~ rjf: @os_hooks GUIDs (Implemented Per-OS)
+
+internal OS_Guid os_make_guid(void);
+internal String8 os_string_from_guid(Arena *arena, OS_Guid guid);
+
+#endif // OS_CORE_H

src/os/core/win32/os_core_win32.h

@@ -0,0 +1,91 @@
+// Copyright (c) 2024 Epic Games Tools
+// Licensed under the MIT license (https://opensource.org/license/mit/)
+
+#ifndef WIN32_H
+#define WIN32_H
+
+////////////////////////////////
+//~ NOTE(allen): Negotiate the windows header include order
+
+#if OS_FEATURE_SOCKET
+#include <WinSock2.h>
+#endif
+
+#include <Windows.h>
+#include <Shlobj.h>
+
+#if OS_FEATURE_GRAPHICAL
+#include <shellscalingapi.h>
+#endif
+
+#if OS_FEATURE_SOCKET
+#include <WS2tcpip.h>
+#include <Mswsock.h>
+#endif
+
+#include <processthreadsapi.h>
+
+////////////////////////////////
+//~ NOTE(allen): File Iterator
+
+typedef struct W32_FileIter W32_FileIter;
+struct W32_FileIter
+{
+  HANDLE handle;
+  WIN32_FIND_DATAW find_data;
+};
+StaticAssert(sizeof(Member(OS_FileIter, memory)) >= sizeof(W32_FileIter), file_iter_memory_size);
+
+////////////////////////////////
+//~ NOTE(allen): Threading Entities
+
+typedef enum W32_EntityKind
+{
+  W32_EntityKind_Null,
+  W32_EntityKind_Thread,
+  W32_EntityKind_Mutex,
+  W32_EntityKind_RWMutex,
+  W32_EntityKind_ConditionVariable,
+}
+W32_EntityKind;
+
+typedef struct W32_Entity W32_Entity;
+struct W32_Entity
+{
+  W32_Entity *next;
+  W32_EntityKind kind;
+  volatile U32 reference_mask;
+  union{
+    struct{
+      OS_ThreadFunctionType *func;
+      void *ptr;
+      HANDLE handle;
+      DWORD tid;
+    } thread;
+    CRITICAL_SECTION mutex;
+    SRWLOCK rw_mutex;
+    CONDITION_VARIABLE cv;
+  };
+};
+
+////////////////////////////////
+//~ rjf: Helpers
+
+//- rjf: files
+internal FilePropertyFlags w32_file_property_flags_from_dwFileAttributes(DWORD dwFileAttributes);
+internal void w32_file_properties_from_attributes(FileProperties *properties, WIN32_FILE_ATTRIBUTE_DATA *attributes);
+
+//- rjf: time
+internal void w32_date_time_from_system_time(DateTime *out, SYSTEMTIME *in);
+internal void w32_system_time_from_date_time(SYSTEMTIME *out, DateTime *in);
+internal void w32_dense_time_from_file_time(DenseTime *out, FILETIME *in);
+internal U32 w32_sleep_ms_from_endt_us(U64 endt_us);
+
+//- rjf: entities
+internal W32_Entity* w32_alloc_entity(W32_EntityKind kind);
+internal void w32_free_entity(W32_Entity *entity);
+
+//- rjf: threads
+internal DWORD w32_thread_base(void *ptr);
+
+#endif //WIN32_H