thread.h

Go to the documentation of this file.

/* -*- C -*-
 * Serene programming language
 * Copyright (C) 2019-2026 Sameer Rahmani <[email protected]>
 *
 * This library is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library.  If not, see <https://www.gnu.org/licenses/>.
 */
 
#pragma once
 
/// @file
/// `srn_thread_t`, `srn_mutex_t`, and `srn_cond_t` model the thread-level
/// operations the runtime needs, with semantics defined here rather than
/// borrowed from one OS API. The status enum and the operation signatures below
/// are platform-neutral. Only the type realizations differ per platform, so
/// each backend defines the three types over its own primitives inside the
/// matching branch. pthreads back them on POSIX. A Windows backend realises the
/// same operations on the Win32 API directly, so neither platform emulates the
/// other. The types are thin wrappers so they embed inline in another struct
/// rather than needing a separate allocation.
///
/// Bear in mind that, we only expose what we need. THIS IS NOT A GENERICE
/// THREAD INTERFACE.
 
#ifdef _WIN32
#  error "Win32 threading is not supported yet"
#else
#  include <pthread.h>
 
typedef struct srn_thread_t {
  pthread_t handle;
  /// The function the thread runs and its argument, recorded by
  /// `srn_thread_spawn` and read once by the backend when the thread starts.
  /// Keeping them on the thread carries them across the start boundary without
  /// an allocation. They are internal and callers do not touch them.
  void (*fn)(void *);
  void *arg;
} srn_thread_t;
 
typedef struct srn_mutex_t {
  pthread_mutex_t handle;
} srn_mutex_t;
 
typedef struct srn_cond_t {
  pthread_cond_t handle;
} srn_cond_t;
#endif
 
/// Result of a thread operation. Each backend maps its own error space onto
/// these, so a caller never sees a pthread or Win32 code.
typedef enum srn_thread_status_t {
  SRN_THREAD_OK = 0,
  /// The system lacked the resources to start the thread, such as a per-process
  /// thread limit. Retrying after others exit may succeed.
  SRN_THREAD_AGAIN,
  /// Out of memory.
  SRN_THREAD_NOMEM,
  /// The caller lacks permission for the requested operation.
  SRN_THREAD_PERM,
  /// A failure the backend could not map to the above.
  SRN_THREAD_ERROR,
} srn_thread_status_t;
 
/// Run `fn(arg)` on a new OS thread. Returns SRN_THREAD_OK, or a status
/// describing why the thread could not be created. The caller owns `t` and must
/// keep it alive until `srn_thread_join` returns.
srn_thread_status_t srn_thread_spawn(srn_thread_t *t, void (*fn)(void *),
                                     void *arg);
 
/// Block until the thread started for `t` returns.
srn_thread_status_t srn_thread_join(srn_thread_t *t);
 
srn_thread_status_t srn_mutex_init(srn_mutex_t *m);
srn_thread_status_t srn_mutex_lock(srn_mutex_t *m);
srn_thread_status_t srn_mutex_unlock(srn_mutex_t *m);
 
/// Release a mutex's resources. The mutex must be unlocked and have no waiters,
/// and must not be used again without a fresh `srn_mutex_init`.
srn_thread_status_t srn_mutex_destroy(srn_mutex_t *m);
 
srn_thread_status_t srn_cond_init(srn_cond_t *c);
 
/// Release `m`, sleep until notified, then re-acquire `m` before returning. A
/// wait can wake spuriously, so the caller must re-check its predicate in a
/// loop.
srn_thread_status_t srn_cond_wait(srn_cond_t *c, srn_mutex_t *m);
 
/// Wake one waiter.
srn_thread_status_t srn_cond_notify_one(srn_cond_t *c);
 
/// Wake every waiter.
srn_thread_status_t srn_cond_notify_all(srn_cond_t *c);
 
/// Release a condition's resources. It must have no waiters, and must not be
/// used again without a fresh `srn_cond_init`.
srn_thread_status_t srn_cond_destroy(srn_cond_t *c);