thread_posix.c

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/>.
 */
 
/** @file
 POSIX implementation of the thread-level operations in `serene/rt/fiber/thread.h`, realised with
 pthreads. The pthreads mutex and condition functions return their error code as the return value
 and leave the global `errno` untouched. Every such code is mapped to an `srn_thread_status_t` so no
 pthread code escapes the public API. The raw code is also logged through `THREAD_LOG`, which is a
 debug-only diagnostic and not part of the interface.
*/
 
// POSIX thread backend, pthreads. On a target without pthreads (Windows) this file compiles to
// nothing and a sibling backend should supply the srn_thread_*/srn_mutex_*/srn_cond_* operations
// instead. The selection is by target macro, so the whole runtime source set can be handed to a
// cross compiler and only the matching backend emits symbols. The include of thread.h sits inside
// the guard because it refuses to compile off a supported threading platform.
#if defined(__unix__) || defined(__APPLE__)
 
#  include <errno.h>
 
#  include "serene/rt/fiber/thread.h"
#  include "serene/utils.h"
 
#  define THREAD_LOG(FMT, ...) DBG("THREAD", FMT __VA_OPT__(, ) __VA_ARGS__)
 
/**
 * Map a pthreads return code onto the neutral status. Anything without a dedicated code (`EDEADLK`,
 * `EINVAL`, `ESRCH`, and so on) becomes `SRN_THREAD_ERROR`. The precise code is recovered from the
 * THREAD_LOG line at the call site.
 */
static srn_thread_status_t status_from_errno(int rc) {
  switch (rc) {
  case 0:
    return SRN_THREAD_OK;
  case EAGAIN:
    return SRN_THREAD_AGAIN;
  case ENOMEM:
    return SRN_THREAD_NOMEM;
  case EPERM:
    return SRN_THREAD_PERM;
  default:
    return SRN_THREAD_ERROR;
  }
}
 
/**
 * `pthreads` run a thread through a `void *(*)(void *)` routine, while the modeled operation runs a
 * `void (*)(void *)`. This trampoline bridges the two, it reads the function and argument the spawn
 * recorded on the thread, runs them, and returns the null pthreads expects.
 */
static void *posix_trampoline(void *arg) {
  srn_thread_t *t = arg;
  t->fn(t->arg);
  return nullptr;
}
 
srn_thread_status_t srn_thread_spawn(srn_thread_t *t, void (*fn)(void *), void *arg) {
  PANIC_IF_NULL(t);
  PANIC_IF_NULL(fn);
 
  t->fn  = fn;
  t->arg = arg;
 
  int rc = pthread_create(&t->handle, nullptr, posix_trampoline, t);
  if (rc != 0) {
    THREAD_LOG("pthread_create failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}
 
srn_thread_status_t srn_thread_join(srn_thread_t *t) {
  PANIC_IF_NULL(t);
  // The thread's return value is discarded. The trampoline always returns null.
  int rc = pthread_join(t->handle, nullptr);
  if (rc != 0) {
    THREAD_LOG("pthread_join failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}
 
srn_thread_status_t srn_mutex_init(srn_mutex_t *m) {
  PANIC_IF_NULL(m);
  int rc = pthread_mutex_init(&m->handle, nullptr);
  if (rc != 0) {
    THREAD_LOG("pthread_mutex_init failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}
 
srn_thread_status_t srn_mutex_lock(srn_mutex_t *m) {
  PANIC_IF_NULL(m);
  int rc = pthread_mutex_lock(&m->handle);
  if (rc != 0) {
    THREAD_LOG("pthread_mutex_lock failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}
 
srn_thread_status_t srn_mutex_unlock(srn_mutex_t *m) {
  PANIC_IF_NULL(m);
  int rc = pthread_mutex_unlock(&m->handle);
  if (rc != 0) {
    THREAD_LOG("pthread_mutex_unlock failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}
 
srn_thread_status_t srn_mutex_destroy(srn_mutex_t *m) {
  PANIC_IF_NULL(m);
  int rc = pthread_mutex_destroy(&m->handle);
  if (rc != 0) {
    THREAD_LOG("pthread_mutex_destroy failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}
 
srn_thread_status_t srn_cond_init(srn_cond_t *c) {
  PANIC_IF_NULL(c);
  int rc = pthread_cond_init(&c->handle, nullptr);
  if (rc != 0) {
    THREAD_LOG("pthread_cond_init failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}
 
srn_thread_status_t srn_cond_wait(srn_cond_t *c, srn_mutex_t *m) {
  PANIC_IF_NULL(c);
  PANIC_IF_NULL(m);
  int rc = pthread_cond_wait(&c->handle, &m->handle);
  if (rc != 0) {
    THREAD_LOG("pthread_cond_wait failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}
 
srn_thread_status_t srn_cond_notify_one(srn_cond_t *c) {
  PANIC_IF_NULL(c);
  int rc = pthread_cond_signal(&c->handle);
  if (rc != 0) {
    THREAD_LOG("pthread_cond_signal failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}
 
srn_thread_status_t srn_cond_notify_all(srn_cond_t *c) {
  PANIC_IF_NULL(c);
  int rc = pthread_cond_broadcast(&c->handle);
  if (rc != 0) {
    THREAD_LOG("pthread_cond_broadcast failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}
 
srn_thread_status_t srn_cond_destroy(srn_cond_t *c) {
  PANIC_IF_NULL(c);
  int rc = pthread_cond_destroy(&c->handle);
  if (rc != 0) {
    THREAD_LOG("pthread_cond_destroy failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}
 
#endif // POSIX thread backend