ppsspp/libretro/libretro-common/include/rthreads/rthreads.h

/* Copyright  (C) 2010-2020 The RetroArch team
 *
 * ---------------------------------------------------------------------------------------
 * The following license statement only applies to this file (rthreads.h).
 * ---------------------------------------------------------------------------------------
 *
 * Permission is hereby granted, free of charge,
 * to any person obtaining a copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
 * and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
 * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

#ifndef __LIBRETRO_SDK_RTHREADS_H__
#define __LIBRETRO_SDK_RTHREADS_H__

#include <retro_common_api.h>

#include <stddef.h>
#include <boolean.h>
#include <stdint.h>
#include <retro_inline.h>
#include <retro_miscellaneous.h>

RETRO_BEGIN_DECLS

/** Platform-agnostic handle to a thread. */
typedef struct sthread sthread_t;

/** Platform-agnostic handle to a mutex. */
typedef struct slock slock_t;

/** Platform-agnostic handle to a condition variable. */
typedef struct scond scond_t;

#ifdef HAVE_THREAD_STORAGE
/** Platform-agnostic handle to thread-local storage. */
typedef unsigned sthread_tls_t;
#endif

/**
 * Creates a new thread and starts running it.
 *
 * @param thread_func Function to run in the new thread.
 * Called with the value given in \c userdata as an argument.
 * @param userdata Pointer to anything (even \c NULL), passed directly to \c thread_func.
 * Must be cleaned up by the caller or the thread.
 * @return Pointer to the new thread,
 * or \c NULL if there was an error.
 * @warn Make sure that the thread can respond to cancellation requests,
 * especially if used in a core.
 * If a core-created thread isn't terminated by the time the core is unloaded,
 * it may leak into the frontend and cause undefined behavior
 * (especially if another session with the core is started).
 */
sthread_t *sthread_create(void (*thread_func)(void*), void *userdata);

/**
 * Creates a new thread with a specific priority hint and starts running it.
 *
 * @param thread_func Function to run in the new thread.
 * Called with the value given in \c userdata as an argument.
 * @param userdata Pointer to anything (even \c NULL), passed directly to \c thread_func.
 * Must be cleaned up by the caller or the thread.
 * @param thread_priority Priority hint for the new thread.
 * Threads with a higher number are more likely to be scheduled first.
 * Should be between 1 and 100, inclusive;
 * if not, the operating system will assign a default priority.
 * May be ignored.
 * @return Pointer to the new thread,
 * or \c NULL if there was an error.
 */
sthread_t *sthread_create_with_priority(void (*thread_func)(void*), void *userdata, int thread_priority);

/**
 * sthread_create_with_stack_size:
 * @thread_func              : function to run in the thread.
 * @userdata                 : pointer passed to @thread_func.
 * @stack_size               : stack size in bytes; 0 keeps the backend's
 *                             default. Honoured on Windows, pthread and
 *                             every console backend whose create takes a
 *                             size. A recompiler that runs the guest on
 *                             the host stack is the caller this is for.
 *
 * Returns: pointer to new thread if successful, otherwise NULL.
 */
sthread_t *sthread_create_with_stack_size(void (*thread_func)(void*), void *userdata, size_t stack_size);

/**
 * sthread_set_affinity:
 * @thread                   : the thread to pin, or the calling thread for
 *                             sthread_set_current_affinity.
 * @mask                     : bit N set allows CPU N; 0 allows every CPU,
 *                             which undoes a pin.
 *
 * Hard affinity where the platform has it: Windows, Linux and Android.
 * Darwin has only a scheduler hint and the consoles have none; those
 * return false and leave the thread where it is.
 *
 * Returns: true if the mask was applied.
 */
bool sthread_set_affinity(sthread_t *thread, uint64_t mask);
bool sthread_set_current_affinity(uint64_t mask);

/**
 * sthread_yield:
 *
 * Gives up the rest of this timeslice to any runnable thread. For the
 * back-off in a bounded spin and for the one place a lock cannot be
 * taken, a fault handler; never a substitute for a real wait.
 */
void sthread_yield(void);

/**
 * Asks the operating system to schedule the calling thread ahead of
 * ordinary threads - a time-critical class on Windows, the audio
 * priority band on Android, real-time round-robin where the POSIX
 * scheduler and the process's limits allow it - on Linux clamped to
 * RLIMIT_RTPRIO, else a lower nice value within RLIMIT_NICE. Best
 * effort: where the request is refused or the platform has no such
 * thing, the thread keeps its default priority and this returns
 * false. Never fails the thread. Meant for a thread that feeds an
 * audio device on a deadline.
 *
 * @return Whether the priority was changed.
 */
bool sthread_raise_current_priority(void);

/**
 * sthread_prefer_fast_cores:
 *
 * Pins the calling thread to the CPUs whose maximum clock is the
 * highest in the system - the big cluster on an asymmetric part - so
 * the scheduler cannot park it on a slow core. On a homogeneous
 * machine, where the platform offers no affinity control, or where
 * the fast cores are outside what this thread may already use, the
 * thread is left where it is and this returns false. Never fails the
 * thread. Meant for the emulation and audio threads.
 *
 * @return Whether the thread was pinned.
 */
bool sthread_prefer_fast_cores(void);

/**
 * sthread_get_core_topology:
 *
 * Counts the physical cores the calling thread may run on, split by
 * class: the fast ones (the big cluster, the P-cores) and the slow
 * ones (the little cluster, the E-cores). SMT siblings count once.
 * On a homogeneous part every core is fast and slow is 0. The class
 * comes from the same source sthread_prefer_fast_cores() pins by.
 *
 * Meant for sizing worker pools: the count of cores a pool may use
 * once the frame-critical threads have theirs, and on a mixed part
 * whether the pool would be spreading onto the slow cluster.
 *
 * @fast : receives the fast core count.
 * @slow : receives the slow core count.
 *
 * Returns: true when the counts are known. On a platform with no
 * topology information at all (the consoles) nothing is written and
 * this returns false; the caller falls back to the thread count.
 */
bool sthread_get_core_topology(unsigned *fast, unsigned *slow);

/**
 * Labels the calling thread for debuggers, crash dumps and system
 * thread listings.
 *
 * Threads that are never labelled inherit the name of whichever thread
 * created them, which on Android leaves several identically-named
 * entries in an ANR report and an unnamed thread id in a tombstone.
 *
 * @param name Label to apply. Keep it under 16 bytes including the
 * terminator: that is the kernel's limit on Linux and Android, and
 * longer names are truncated to fit rather than rejected.
 * @warn Does nothing on platforms with no thread-naming interface.
 */
void sthread_setname(const char *name);

/**
 * Detaches the given thread.
 *
 * When a detached thread terminates,
 * its resources are automatically released back to the operating system
 * without needing another thread to join with it.
 *
 * @param thread Thread to detach.
 * @return 0 on success, a non-zero error code on failure.
 * @warn Once a thread is detached, it cannot be joined.
 * @see sthread_join
 */
int sthread_detach(sthread_t *thread);

/**
 * Waits for the given thread to terminate.
 *
 * @param thread The thread to wait for.
 * Must be joinable.
 * Returns immediately if it's already terminated
 * or if it's \c NULL.
 */
void sthread_join(sthread_t *thread);

/**
 * Returns whether the given thread is the same as the calling thread.
 *
 * @param thread Thread to check.
 * @return \c true if \c thread is the same as the calling thread,
 * \c false if not or if it's \c NULL.
 * @note libretro does not have a notion of a "main" thread,
 * since the core may not be running on the same thread
 * that called \c main (or local equivalent).
 * @see sthread_get_thread_id
 */
bool sthread_isself(sthread_t *thread);

/**
 * Creates a new mutex (a.k.a. lock) that can be used to synchronize shared data.
 *
 * Must be manually freed with \c slock_free.
 *
 * @return Pointer to the new mutex,
 * or \c NULL if there was an error.
 */
slock_t *slock_new(void);

/**
 * Frees a mutex.
 *
 * Behavior is undefined if \c lock was previously freed.
 *
 * @param lock Pointer to the mutex to free.
 * May be \c NULL, in which this function does nothing.
 */
void slock_free(slock_t *lock);

/**
 * Locks a mutex, preventing other threads from claiming it until it's unlocked.
 *
 * If the mutex is already locked by another thread,
 * the calling thread will block until the mutex is unlocked.
 *
 * @param lock Pointer to the mutex to lock.
 * If \c NULL, will return without further action.
 * @see slock_try_lock
 */
void slock_lock(slock_t *lock);

/**
 * Tries to lock a mutex if it's not already locked by another thread.
 *
 * If the mutex is already in use by another thread,
 * returns immediately without waiting for it.
 *
 * @param lock The mutex to try to lock.
 * @return \c true if the mutex was successfully locked,
 * \c false if it was already locked by another thread or if \c lock is \c NULL.
 * @see slock_lock
 */
bool slock_try_lock(slock_t *lock);

/**
 * Unlocks a mutex, allowing other threads to claim it.
 *
 * @post The mutex is unlocked,
 * and another thread may lock it.
 * @param lock The mutex to unlock.
 * If \c NULL, this function is a no-op.
 */
void slock_unlock(slock_t *lock);

/**
 * Creates and initializes a condition variable.
 *
 * Must be manually freed with \c scond_free.
 *
 * @return Pointer to the new condition variable,
 * or \c NULL if there was an error.
 */
scond_t *scond_new(void);

/**
 * Frees a condition variable.
 *
 * @param cond Pointer to the condition variable to free.
 * If \c NULL, this function is a no-op.
 * Behavior is undefined if \c cond was previously freed.
 */
void scond_free(scond_t *cond);

/**
 * Blocks until the given condition variable is signaled or broadcast.
 *
 * @param cond Condition variable to wait on.
 * This function blocks until another thread
 * calls \c scond_signal or \c scond_broadcast with this condition variable.
 * @param lock Mutex to lock while waiting.
 *
 * @see scond_signal
 * @see scond_broadcast
 * @see scond_wait_timeout
 */
void scond_wait(scond_t *cond, slock_t *lock);

/**
 * Blocks until the given condition variable is signaled or broadcast,
 * or until the specified time has passed.
 *
 * @param cond Condition variable to wait on.
 * This function blocks until another thread
 * calls \c scond_signal or \c scond_broadcast with this condition variable.
 * @param lock Mutex to lock while waiting.
 * @param timeout_us Time to wait for a signal, in microseconds.
 *
 * @return \c false if \c timeout_us elapses
 * before \c cond is signaled or broadcast, otherwise \c true.
 */
bool scond_wait_timeout(scond_t *cond, slock_t *lock, int64_t timeout_us);

/**
 * Unblocks all threads waiting on the specified condition variable.
 *
 * @param cond Condition variable to broadcast.
 * @return 0 on success, non-zero on failure.
 */
int scond_broadcast(scond_t *cond);

/**
 * Unblocks at least one thread waiting on the specified condition variable.
 *
 * @param cond Condition variable to signal.
 */
void scond_signal(scond_t *cond);

#ifdef HAVE_THREAD_STORAGE
/**
 * Creates a thread-local storage key.
 *
 * Thread-local storage keys have a single value associated with them
 * that is unique to the thread that uses them.
 *
 * New thread-local storage keys have a value of \c NULL for all threads,
 * and new threads initialize all existing thread-local storage to \c NULL.
 *
 * @param tls[in,out] Pointer to the thread local storage key that will be initialized.
 * Must be cleaned up with \c sthread_tls_delete.
 * Behavior is undefined if \c NULL.
 * @return \c true if the operation succeeded, \c false otherwise.
 * @see sthread_tls_delete
 */
bool sthread_tls_create(sthread_tls_t *tls);

/**
 * Like sthread_tls_create(), but registers a destructor invoked with the
 * thread-local value when a thread exits with a non-NULL value set for
 * this key (POSIX pthread_key_create semantics). Used e.g. to release a
 * per-thread resource such as a JNI attachment on thread teardown.
 *
 * The destructor is honoured on pthread backends; on Win32 the key is
 * created without one (TlsAlloc has no destructor callback), so callers
 * needing cleanup there must do it explicitly. Current users are POSIX.
 *
 * @param tls[in,out] Pointer to the key to initialize; must be cleaned up
 * with sthread_tls_delete. Behavior is undefined if NULL.
 * @param destructor Called with the thread-local value on thread exit;
 * may be NULL for no destructor (equivalent to sthread_tls_create).
 * @return true if the operation succeeded, false otherwise.
 * @see sthread_tls_create
 * @see sthread_tls_delete
 */
bool sthread_tls_create_with_dtor(sthread_tls_t *tls,
      void (*destructor)(void *value));

/**
 * Deletes a thread local storage key.
 *
 * The value must be cleaned up separately \em before calling this function,
 * if necessary.
 *
 * @param tls The thread local storage key to delete.
 * Behavior is undefined if \c NULL.
 * @return \c true if the operation succeeded, \c false otherwise.
 */
bool sthread_tls_delete(sthread_tls_t *tls);

/**
 * Gets the calling thread's local data for the given key.
 *
 * @param tls The thread-local storage key to get the data for.
 * @return The calling thread's local data associated with \c tls,
 * which should previously have been set with \c sthread_tls_set.
 * Will be \c NULL if this thread has not set a value or if there was an error.
 */
void *sthread_tls_get(sthread_tls_t *tls);

/**
 * Sets the calling thread's local data for the given key.
 *
 * @param tls The thread-local storage key to set the data for.
 * @param data Pointer to the data that will be associated with \c tls.
 * May be \c NULL.
 * @return \c true if \c data was successfully assigned to \c tls,
 * \c false if there was an error.
 */
bool sthread_tls_set(sthread_tls_t *tls, const void *data);
#endif

/**
 * Gets a thread's unique ID.
 *
 * @param thread The thread to get the ID of.
 * @return The provided thread's ID,
 * or 0 if it's \c NULL.
 */
uintptr_t sthread_get_thread_id(sthread_t *thread);

/**
 * Get the calling thread's unique ID.
 * @return The calling thread's ID.
 * @see sthread_get_thread_id
 */
uintptr_t sthread_get_current_thread_id(void);

/**
 * Returns whether the calling thread is the process's main/initial thread.
 *
 * Implemented where the platform exposes a native predicate (currently
 * Apple/Darwin, via pthread_main_np()); returns false on backends that
 * provide no such primitive. All present callers run on Apple. A fully
 * portable implementation would compare sthread_get_current_thread_id()
 * against a main-thread id captured at startup (cf. task_is_on_main_thread()
 * in queues/task_queue.c).
 *
 * @return true if called from the main thread; false otherwise, or if the
 * platform offers no way to tell.
 */
bool sthread_is_main_thread(void);

/**
 * Enable or defer cancellation of the CALLING thread (POSIX-style
 * deferred cancellation). Bracket a critical section that must not be
 * interrupted (e.g. one holding an open file or other resource) with
 * sthread_set_cancel_enable(false) ... sthread_set_cancel_enable(true).
 *
 * A no-op on backends without thread cancellation (Win32, Android/Bionic,
 * GEKKO, 3DS, PSP, Vita, WiiU, Switch, PS2); pair it with a cooperative "done" flag so shutdown does not
 * rely on cancellation being available.
 *
 * @param enable true to allow cancellation, false to defer it.
 */
void sthread_set_cancel_enable(bool enable);

/**
 * Request cancellation of @thread. Intended to interrupt a thread blocked
 * at a cancellation point (e.g. a sleep) so it can exit promptly; the
 * caller should still set a cooperative stop flag and sthread_join().
 *
 * @param thread The thread to cancel.
 * @return true if the request was issued; false on failure or where the
 * backend provides no cancellation (Win32, Android/Bionic, GEKKO, 3DS, PSP, Vita, WiiU, Switch, PS2).
 */
bool sthread_cancel(sthread_t *thread);

/**
 * Temporarily raise the CALLING thread's scheduling priority to match a
 * higher-priority thread that is synchronously waiting on it, mitigating a
 * priority inversion across an slock/scond handoff. Unlike some OS-native
 * locks, sthread's lock/condvar primitives do not propagate priority
 * automatically, so a low-priority worker executing work a high-priority
 * thread is blocked on will not be boosted on its own.
 *
 * Must be paired with sthread_priority_override_end(). Returns an opaque
 * handle to pass to that call, or \c NULL when the platform provides no
 * such mechanism (in which case _end() is a no-op). Scoped to the current
 * thread; needs no handle to the waiting thread.
 *
 * @return An opaque override handle, or \c NULL if unsupported.
 * @see sthread_priority_override_end
 */
void *sthread_priority_override_begin(void);

/**
 * End a priority override previously started on the calling thread with
 * sthread_priority_override_begin(), restoring its prior scheduling
 * priority.
 *
 * @param ovr Handle from sthread_priority_override_begin(); may be
 * \c NULL, in which case this is a no-op.
 * @see sthread_priority_override_begin
 */
void sthread_priority_override_end(void *ovr);

RETRO_END_DECLS

#endif