nanocoat/include/sjme/multithread.h

   1 /* -*- Mode: C; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // -------------------------------------------------------------------------*/
   9
  10 /**
  11  * Multithreaded support.
  12  *
  13  * @since 2023/12/16
  14  */
  15
  16 #ifndef SQUIRRELJME_MULTITHREAD_H
  17 #define SQUIRRELJME_MULTITHREAD_H
  18
  19 #include "sjme/config.h"
  20 #include "sjme/error.h"
  21
  22 #if defined(SJME_CONFIG_HAS_THREADS_FALLBACK)
  23         /* Clear pthreads. */
  24         #if defined(SJME_CONFIG_HAS_THREADS_PTHREAD)
  25                 #undef SJME_CONFIG_HAS_THREADS_PTHREAD
  26         #endif
  27
  28         /* Clear Win32 threads. */
  29         #if defined(SJME_CONFIG_HAS_THREADS_WIN32)
  30                 #undef SJME_CONFIG_HAS_THREADS_WIN32
  31         #endif
  32 #endif
  33
  34 #if defined(SJME_CONFIG_HAS_THREADS_WIN32)
  35         #define WIN32_LEAN_AND_MEAN 1
  36
  37         #include <windows.h>
  38
  39         #undef WIN32_LEAN_AND_MEAN
  40 #endif
  41
  42 #if defined(SJME_CONFIG_HAS_THREADS_PTHREAD)
  43         #include <pthread.h>
  44         #include <errno.h>
  45 #else
  46         #if !defined(SJME_CONFIG_HAS_THREADS_ATOMIC)
  47                 #define SJME_CONFIG_HAS_THREADS_ATOMIC
  48         #endif
  49 #endif
  50
  51 #include "sjme/stdTypes.h"
  52 #include "sjme/atomic.h"
  53
  54 /* Anti-C++. */
  55 #ifdef __cplusplus
  56         #ifndef SJME_CXX_IS_EXTERNED
  57                 #define SJME_CXX_IS_EXTERNED
  58                 #define SJME_CXX_SQUIRRELJME_MULTITHREAD_H
  59 extern "C" {
  60         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  61 #endif     /* #ifdef __cplusplus */
  62
  63 /*--------------------------------------------------------------------------*/
  64
  65 /* clang-format off */
  66
  67 #if defined(SJME_CONFIG_HAS_THREADS_PTHREAD)
  68         /** A single thread. */
  69         typedef pthread_t sjme_thread;
  70
  71         /* On these systems pthread_t is a pointer. */
  72         #if defined(SJME_CONFIG_HAS_MACOS) || \
  73                 defined(SJME_CONFIG_HAS_EMSCRIPTEN)
  74                 /** The thread type. */
  75                 #define SJME_TYPEOF_BASIC_sjme_thread SJME_TYPEOF_BASIC_sjme_pointer
  76
  77                 /** Is a thread a pointer? */
  78                 #define SJME_TYPEOF_IS_POINTER_sjme_thread 1
  79         #else
  80                 /** The thread type. */
  81                 #define SJME_TYPEOF_BASIC_sjme_thread SJME_TYPEOF_BASIC_sjme_intPointer
  82
  83                 /** Is a thread a pointer? */
  84                 #define SJME_TYPEOF_IS_POINTER_sjme_thread 0
  85         #endif
  86
  87         /** Thread result. */
  88         typedef sjme_pointer sjme_thread_result;
  89
  90         /** Thread parameter. */
  91         typedef sjme_pointer sjme_thread_parameter;
  92
  93         /** Null thread handle. */
  94         #define SJME_THREAD_NULL ((unsigned long)0)
  95
  96         /** Error as thread result. */
  97         #define SJME_THREAD_RESULT(err) ((sjme_pointer)(err))
  98
  99         /** Thread result cast to error. */
 100         #define SJME_THREAD_RESULT_AS_ERROR(result) \
 101                 ((sjme_errorCode)((sjme_intPointer)(result)))
 102
 103         /** Calling convention to use for thread entry points. */
 104         #define sjme_attrThreadCall
 105 #elif defined(SJME_CONFIG_HAS_THREADS_WIN32)
 106         /** A single thread. */
 107         typedef HANDLE sjme_thread;
 108
 109         /** The thread type. */
 110         #define SJME_TYPEOF_BASIC_sjme_thread SJME_TYPEOF_BASIC_sjme_pointer
 111
 112         /** Is a thread a pointer? */
 113         #define SJME_TYPEOF_IS_POINTER_sjme_thread 1
 114
 115         /** Thread result. */
 116         typedef DWORD sjme_thread_result;
 117
 118         /** Thread parameter. */
 119         typedef LPVOID sjme_thread_parameter;
 120
 121         /** Null thread handle. */
 122         #define SJME_THREAD_NULL NULL
 123
 124         /** Error as thread result. */
 125         #define SJME_THREAD_RESULT(err) ((DWORD)(err))
 126
 127         /** Thread result cast to error. */
 128         #define SJME_THREAD_RESULT_AS_ERROR(result) ((sjme_errorCode)(result))
 129
 130         /** Calling convention to use for thread entry points. */
 131         #define sjme_attrThreadCall WINAPI
 132 #else
 133         /** Threads not supported. */
 134         typedef struct sjme_thread_unsupported
 135         {
 136                 int unsupported;
 137         } sjme_thread_unsupported;
 138
 139         /** A single thread. */
 140         typedef sjme_thread_unsupported* sjme_thread;
 141
 142         /** The thread type. */
 143         #define SJME_TYPEOF_BASIC_sjme_thread SJME_TYPEOF_BASIC_sjme_pointer
 144
 145         /** Is a thread a pointer? */
 146         #define SJME_TYPEOF_IS_POINTER_sjme_thread 1
 147
 148         /** Thread result. */
 149         typedef int sjme_thread_result;
 150
 151         /** Thread parameter. */
 152         typedef sjme_pointer sjme_thread_parameter;
 153
 154         /** Null thread handle. */
 155         #define SJME_THREAD_NULL NULL
 156
 157         /** Error as thread result. */
 158         #define SJME_THREAD_RESULT(err) ((int)(err))
 159
 160         /** Thread result cast to error. */
 161         #define SJME_THREAD_RESULT_AS_ERROR(result) ((sjme_errorCode)(result))
 162
 163         /** Calling convention to use for thread entry points. */
 164         #define sjme_attrThreadCall
 165 #endif
 166
 167 /* clang-format on */
 168 /*--*/
 169
 170 SJME_ATOMIC_DECLARE(sjme_thread, 0);
 171
 172 /**
 173  * Main thread function type.
 174  *
 175  * @param anything Passed from @c sjme_thread_new .
 176  * @return Thread resultant value.
 177  * @since 2024/04/16
 178  */
 179 typedef sjme_thread_result (sjme_attrThreadCall *sjme_thread_mainFunc)(
 180         sjme_attrInNullable sjme_thread_parameter anything);
 181
 182 /**
 183  * Basic spin lock.
 184  *
 185  * @since 2024/07/19
 186  */
 187 typedef struct sjme_thread_spinLock
 188 {
 189         /** The thread that is currently poking this lock. */
 190         sjme_atomic_sjme_thread poke;
 191
 192         /** The thread that owns this lock. */
 193         sjme_atomic_sjme_thread owner;
 194
 195         /** Lock count. */
 196         sjme_atomic_sjme_jint count;
 197 } sjme_thread_spinLock;
 198
 199 /**
 200  * Returns the current thread.
 201  *
 202  * @param outThread The resultant thread.
 203  * @return On any errors if applicable.
 204  * @since 2024/04/16
 205  */
 206 sjme_errorCode sjme_thread_current(
 207         sjme_attrInOutNotNull sjme_thread* outThread);
 208
 209 /**
 210  * Compares equality between two threads.
 211  *
 212  * @param aThread The first thread.
 213  * @param bThread The second thread.
 214  * @return The resultant equality.
 215  * @since 2024/04/16
 216  */
 217 sjme_jboolean sjme_thread_equal(
 218         sjme_attrInNullable sjme_thread aThread,
 219         sjme_attrInNullable sjme_thread bThread);
 220
 221 /**
 222  * Creates a new thread and immediately starts running it.
 223  *
 224  * @param outThread The resultant thread.
 225  * @param outThreadId The resultant thread ID, is optional.
 226  * @param inMain The main function for the thread.
 227  * @param anything Any value to pass to it.
 228  * @return Any error code if applicable.
 229  * @since 2024/04/16
 230  */
 231 sjme_errorCode sjme_thread_new(
 232         sjme_attrInOutNotNull sjme_thread* outThread,
 233         sjme_attrInNullable sjme_intPointer* outThreadId,
 234         sjme_attrInNotNull sjme_thread_mainFunc inMain,
 235         sjme_attrInNullable sjme_pointer anything);
 236
 237 /**
 238  * Grabs a spin lock.
 239  *
 240  * @param inLock The lock to grab.
 241  * @return Any resultant error, if any.
 242  * @since 2024/07/19
 243  */
 244 sjme_errorCode sjme_thread_spinLockGrab(sjme_thread_spinLock* inLock);
 245
 246 /**
 247  * Releases a spin lock.
 248  *
 249  * @param inLock The lock to release.
 250  * @param outCount Optional count after lock.
 251  * @return Any resultant error, if any.
 252  * @since 2024/07/19
 253  */
 254 sjme_errorCode sjme_thread_spinLockRelease(
 255         sjme_attrInNotNull sjme_thread_spinLock* inLock,
 256         sjme_attrOutNullable sjme_jint* outCount);
 257
 258 /**
 259  * Yields execution.
 260  *
 261  * @since 2024/04/17
 262  */
 263 void sjme_thread_yield(void);
 264
 265 /*--------------------------------------------------------------------------*/
 266
 267 /* Anti-C++. */
 268 #ifdef __cplusplus
 269         #ifdef SJME_CXX_SQUIRRELJME_MULTITHREAD_H
 270 }
 271                 #undef SJME_CXX_SQUIRRELJME_MULTITHREAD_H
 272                 #undef SJME_CXX_IS_EXTERNED
 273         #endif /* #ifdef SJME_CXX_SQUIRRELJME_MULTITHREAD_H */
 274 #endif     /* #ifdef __cplusplus */
 275
 276 #endif /* SQUIRRELJME_MULTITHREAD_H */