/*
 * Copyright(c) 2006 to 2022 ZettaScale Technology and others
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
 * v. 1.0 which is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
 */
/**
 * @file threads.h
 * @brief Thread management and creation.
 *
 * Platform independent interface for managing and creating execution threads.
 */
#ifndef DDSRT_THREADS_H
#define DDSRT_THREADS_H

#include <stdbool.h>
#include <stdint.h>

#include "dds/config.h"
#include "dds/export.h"
#include "dds/ddsrt/attributes.h"
#include "dds/ddsrt/retcode.h"
#include "dds/ddsrt/sched.h"

#if DDSRT_WITH_FREERTOS
#include "dds/ddsrt/threads/freertos.h"
#elif _WIN32
#include "dds/ddsrt/threads/windows.h"
#else
#include "dds/ddsrt/threads/posix.h"
#endif

#if defined (__cplusplus)
extern "C" {
#endif

#if defined(_MSC_VER) || __MINGW__
  /* Thread-local storage using __declspec(thread) on Windows versions before
     Vista and Server 2008 works in DLLs if they are bound to the executable,
     it does not work if the library is loaded using LoadLibrary. */
#define ddsrt_thread_local __declspec(thread)
#elif defined(__GNUC__) || (defined(__clang__) && __clang_major__ >= 2)
  /* GCC supports Thread-local storage for x86 since version 3.3. Clang
     supports Thread-local storage since version 2.0. */
  /* VxWorks 7 supports __thread for both GCC and DIAB, older versions may
     support it as well, but that is not verified. */
#define ddsrt_thread_local __thread
#elif defined(__SUNPRO_C) || defined(__SUNPRO_CC)
#define ddsrt_thread_local __thread
#else
#error "Thread-local storage is not supported"
#endif

/**
 * @brief Definition for a thread routine invoked on thread create.
 */
typedef uint32_t (*ddsrt_thread_routine_t)(void*);

/**
 * @brief Definition of the thread attributes
 */
typedef struct {
  /** Specifies the scheduling class */
  ddsrt_sched_t schedClass;
  /** Specifies the thread priority */
  int32_t schedPriority;
  /** Specifies the thread stack size */
  uint32_t stackSize;
} ddsrt_threadattr_t;

/**
 * @brief Initialize thread attributes to platform defaults.
 */
DDS_EXPORT void
ddsrt_threadattr_init(
   ddsrt_threadattr_t *attr)
ddsrt_nonnull_all;

/**
 * @brief Create a new thread.
 *
 * Creates a new thread of control that executes concurrently with
 * the calling thread. The new thread applies the function start_routine
 * passing it arg as first argument.
 *
 * The new thread terminates by returning from the start_routine function.
 * The created thread is identified by the returned threadId.
 *
 * @param[out]  thread         Location where thread id is stored.
 * @param[in]   name           Name assigned to created thread.
 * @param[in]   attr           Attributes to create thread with.
 * @param[in]   start_routine  Function to execute in created thread.
 * @param[in]   arg            Argument passed to @start_routine.
 *
 * @returns A dds_return_t indicating success or failure.
 *
 * @retval DDS_RETCODE_OK
 *             Thread successfully created.
 * @retval DDS_RETCODE_ERROR
 *             Thread could not be created.
 */
DDS_EXPORT dds_return_t
ddsrt_thread_create(
  ddsrt_thread_t *thread,
  const char *name,
  const ddsrt_threadattr_t *attr,
  ddsrt_thread_routine_t start_routine,
  void *arg)
ddsrt_nonnull((1,2,3,4));

/**
 * @brief Retrieve integer representation of the given thread id.
 *
 * @returns The integer representation of the current thread.
 */
DDS_EXPORT ddsrt_tid_t
ddsrt_gettid(void);

/**
 * @brief Retrieve integer representation of the given thread id.
 *
 * @returns The integer representation of the given thread.
 */
DDS_EXPORT ddsrt_tid_t
ddsrt_gettid_for_thread( ddsrt_thread_t thread);


/**
 * @brief Return thread ID of the calling thread.
 *
 * @returns Thread ID of the calling thread.
 */
DDS_EXPORT ddsrt_thread_t
ddsrt_thread_self(void);

/**
 * @brief Compare thread identifiers.
 *
 * @returns true if thread ids match, otherwise false.
 */
DDS_EXPORT bool
ddsrt_thread_equal(ddsrt_thread_t t1, ddsrt_thread_t t2);

/**
 * @brief Wait for termination of the specified thread.
 *
 * If the specified thread is still running, wait for its termination
 * else return immediately. In thread_result it returns the exit status
 * of the thread. If NULL is passed for @thread_result, no exit status is
 * returned, but ddsrt_thread_join still waits for the thread to terminate.
 *
 * @param[in]   thread         Id of thread to wait for.
 * @param[out]  thread_result  Location where thread result is stored.
 *
 * @returns A dds_return_t indicating success or failure.
 *
 * @retval DDS_RETCODE_OK
 *             Target thread terminated.
 * @retval DDS_RETCODE_ERROR
 *             An error occurred while waiting for the thread to terminate.
 */
DDS_EXPORT dds_return_t
ddsrt_thread_join(
  ddsrt_thread_t thread,
  uint32_t *thread_result);

/**
 * @brief Get name of current thread.
 *
 * @param[in]  name  Buffer where the name is copied to.
 * @param[in]  size  Number of bytes available in the buffer.
 *
 * @returns The number of bytes (excluding the null terminating bytes) that
 *          are written. If the buffer is not sufficiently large enough, the
 *          name is truncated and the number of bytes that would have been
 *          written is returned.
 */
DDS_EXPORT size_t
ddsrt_thread_getname(
  char *__restrict name,
  size_t size);

/**
 * @brief Set name of current thread.
 *
 * Set name of the current thread to @name. If the name is longer than the
 * platform maximum, it is silently truncated.
 *
 * @param[in]  name  Name for current thread.
 */
#if DDSRT_HAVE_THREAD_SETNAME
DDS_EXPORT void
ddsrt_thread_setname(
  const char *__restrict name);
#endif

#if DDSRT_HAVE_THREAD_LIST
/**
 * @brief Get a list of threads in the calling process
 *
 * @param[out]  tids    Array of size elements to be filled with thread
 *                      identifiers, may be NULL if size is 0
 * @param[in]   size    The size of the tids array; 0 is allowed
 *
 * @returns A dds_return_t indicating the number of threads in the process
 * or an error code on failure.
 *
 * @retval > 0
 *             Number of threads in the process, may be larger than size
 *             tids[0 .. (return - 1)] are valid
 * @retval DDS_RETCODE_ERROR
 *             Something went wrong, contents of tids is undefined
 * @retval DDS_RETCODE_UNSUPPORTED
 *             Not supported on the platform
 */
DDS_EXPORT dds_return_t ddsrt_thread_list (ddsrt_thread_list_id_t * __restrict tids, size_t size);

/**
 * @brief Get the name of the specified thread (in the calling process)
 *
 * @param[in]   tid     Thread identifier for which the name is sought
 * @param[out]  name    Filled with the thread name (or a synthesized one)
 *                      on successful return; name is silently truncated
 *                      if the actual name is longer than name can hold;
 *                      always 0-terminated if size > 0
 * @param[in]   size    Number of bytes of name that may be assigned, size
 *                      is 0 is allowed, though somewhat useless
 *
 * @returns A dds_return_t indicating success or failure.
 *
 * @retval DDS_RETCODE_OK
 *             Possibly truncated name is returned as a null-terminated
 *             string in name (provided size > 0).
 * @retval DDS_RETCODE_NOT_FOUND
 *             Thread not found; the contents of name is unchanged
 * @retval DDS_RETCODE_ERROR
 *             Unspecified failure, the contents of name is undefined
 * @retval DDS_RETCODE_UNSUPPORTED
 *             Not supported on the platform
 */
DDS_EXPORT dds_return_t ddsrt_thread_getname_anythread (ddsrt_thread_list_id_t tid, char *__restrict name, size_t size);
#endif

/**
 * @brief Push cleanup handler onto the cleanup stack
 *
 * Push a cleanup handler onto the top of the calling thread's cleanup
 * stack. The cleanup handler will be popped of the thread's cleanup stack
 * and invoked with the specified argument when the thread exits.
 *
 * @param[in]  routine  Cleanup handler to push onto the thread cleanup stack.
 * @param[in]  arg      Argument that will be passed to the cleanup handler.
 */
DDS_EXPORT dds_return_t
ddsrt_thread_cleanup_push(
  void (*routine)(void*),
  void *arg);

/**
 * @brief Pop cleanup handler from the top of the cleanup stack
 *
 * Remove routine at the top of the calling thread's cleanup stack and
 * optionally invoke it (if execute is non-zero).
 */
DDS_EXPORT dds_return_t
ddsrt_thread_cleanup_pop(
  int execute);

/**
 * @brief Initialize thread internals.
 *
 * Initialize internals for threads not created with @ddsrt_create_thread. By
 * default initialization is done automatically.
 */
DDS_EXPORT void
ddsrt_thread_init(uint32_t reason);

/**
 * @brief Free thread resources and execute cleanup handlers.
 *
 * Platforms that support it, automatically free resources claimed by the
 * current thread and call any registered cleanup routines. This function only
 * needs to be called on platforms that do not support thread destructors and
 * only for threads that were not created with @ddsrt_thread_create.
 */
DDS_EXPORT void
ddsrt_thread_fini(uint32_t reason);

#if defined (__cplusplus)
}
#endif

#endif /* DDSRT_THREADS_H */