include/fosa_threads_and_signals.h

   1 // -----------------------------------------------------------------------
   2 //  Copyright (C) 2006 - 2007 FRESCOR consortium partners:
   3 //
   4 //    Universidad de Cantabria,              SPAIN
   5 //    University of York,                    UK
   6 //    Scuola Superiore Sant'Anna,            ITALY
   7 //    Kaiserslautern University,             GERMANY
   8 //    Univ. Politecnica  Valencia,           SPAIN
   9 //    Czech Technical University in Prague,  CZECH REPUBLIC
  10 //    ENEA                                   SWEDEN
  11 //    Thales Communication S.A.              FRANCE
  12 //    Visual Tools S.A.                      SPAIN
  13 //    Rapita Systems Ltd                     UK
  14 //    Evidence                               ITALY
  15 //
  16 //    See http://www.frescor.org for a link to partners' websites
  17 //
  18 //           FRESCOR project (FP6/2005/IST/5-034026) is funded
  19 //        in part by the European Union Sixth Framework Programme
  20 //        The European Union is not liable of any use that may be
  21 //        made of this code.
  22 //
  23 //  This file is part of the FRSH implementation
  24 //
  25 //  FRSH is free software; you can  redistribute it and/or  modify
  26 //  it under the terms of  the GNU General Public License as published by
  27 //  the Free Software Foundation;  either  version 2, or (at  your option)
  28 //  any later version.
  29 //
  30 //  FRSH  is distributed  in  the hope  that  it  will  be useful,  but
  31 //  WITHOUT  ANY  WARRANTY;     without  even the   implied   warranty  of
  32 //  MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR PURPOSE. See  the  GNU
  33 //  General Public License for more details.
  34 //
  35 //  You should have  received a  copy of  the  GNU  General Public License
  36 //  distributed  with  FRSH;  see file COPYING.   If not,  write to the
  37 //  Free Software  Foundation,  59 Temple Place  -  Suite 330,  Boston, MA
  38 //  02111-1307, USA.
  39 //
  40 //  As a special exception, if you include this header file into source
  41 //  files to be compiled, this header file does not by itself cause
  42 //  the resulting executable to be covered by the GNU General Public
  43 //  License.  This exception does not however invalidate any other
  44 //  reasons why the executable file might be covered by the GNU General
  45 //  Public License.
  46 // -----------------------------------------------------------------------
  47 //fosa_thread_and_signals.h
  48 //==============================================
  49 //  ********  ******    ********  **********
  50 //  **///// /**    **  **//////  /**     /**
  51 //  **      /**    ** /**        /**     /**
  52 //  ******* /**    ** /********* /**********
  53 //  **////  /**    ** ////////** /**//////**
  54 //  **      /**    **        /** /**     /**
  55 //  **      /**    **  ********  /**     /**
  56 //  //       /******/  ////////   //      //
  57 //
  58 // FOSA(Frescor Operating System Adaptation layer)
  59 //================================================
  60
  61
  62 #ifndef         FOSA_THREAD_AND_SIGNALS_H_
  63 #define         FOSA_THREAD_AND_SIGNALS_H_
  64
  65 #include "fosa_types.h"
  66
  67 /**
  68  * @defgroup threadandsignals Thread and Signals
  69  * @ingroup fosa
  70  *
  71  * This module defines the functions that manipulate frsh_threads and
  72  * frsh_signals inside FRSH implementation.
  73  *
  74  * Applications can refer to FRSH threads but they cannot create them
  75  * directly, instead they must use frsh_thread_create*() which in turn
  76  * use fosa_thread_create().
  77  *
  78  * For signals, we assume that the OS provides a direct mapping
  79  * for frsh_signal_t and frsh_signal_info_t in the native interface.
  80  *
  81  * @{
  82  **/
  83
  84
  85
  86 /*************************
  87  * Thread identification
  88  *************************/
  89
  90 /**
  91  * fosa_thread_equal()
  92  *
  93  * Compare two thread identifiers to determine if they refer to the
  94  * same thread
  95  **/
  96 bool fosa_thread_equal(frsh_thread_id_t t1, frsh_thread_id_t t2);
  97
  98
  99 /**
 100  * fosa_thread_self()
 101  *
 102  * Return the thread id of the calling thread
 103  **/
 104 frsh_thread_id_t fosa_thread_self();
 105
 106
 107 /*************************
 108  * Thread creation and termination
 109  *************************/
 110
 111 /**
 112  * fosa_thread_create()
 113  *
 114  * This function creates a new thread using the attributes specified
 115  * in attr. If attr is NULL, default attributes are used. The new
 116  * thread starts running immediately, executing the function specified
 117  * by code, with an argument equal to arg. Upon successful return, the
 118  * variable pointed to by tid will contain the identifier of the newly
 119  * created thread. The set of signals that may be synchronously
 120  * accepted is inherited from the parent thread.
 121  *
 122  * Returns 0 if successful; otherwise it returs a code error:
 123  *
 124  *     EAGAIN: the system lacks the necessary resources to create a
 125  *             new thread or the maximum number of threads has been
 126  *             reached
 127  *
 128  *     EINVAL: the value specified by attr is invalid (for instance,
 129  *              it has not been correctly initialized)
 130  *
 131  *     EREJECT: the cretion of the thread was rejected by the frsh scheduler
 132  *               possibly because of incorrect attributes, or because the
 133  *               requested minimum capacity cannot be guaranteed
 134  *
 135  **/
 136  int fosa_thread_create
 137     (frsh_thread_id_t *tid, const frsh_thread_attr_t *attr,
 138      frsh_thread_code_t code, void * arg);
 139
 140
 141 /**
 142  * Note: no thread termination primitive is provided. The termination
 143  * of a thread will be notified by the system to the FRSH scheduler
 144  * through the scheduler API
 145  **/
 146
 147
 148 /**************************************************
 149  * Thread-specific data
 150  *  (extended with access from a different thread)
 151  *
 152  * Several data items (pointers) may be associated with each thread
 153  * Each item is identified through a key, an integer value between 0
 154  * and FOSA_MAX_KEYS-1. The caller is responsible of allocating and
 155  * deallocating the memory area pointed to by the pointer
 156  **************************************************/
 157
 158 /**
 159  * fosa_key_create()
 160  *
 161  * Create a new key for thread specific data.
 162  *
 163  * Prior to setting data in a key, we need ask the system to create
 164  * one for us.
 165  *
 166  * @return 0 if successful \n
 167  *   FOSA_EINVAL If we already have reached the FOSA_MAX_KEYS limit.
 168  *   FOSA_ENOMEM If there are no enough memory resources to
 169  *               create the key.
 170  **/
 171 int fosa_key_create(int *key);
 172
 173 /**
 174  * fosa_key_destroy()
 175  *
 176  * Destroy a key
 177  *
 178  * This destroys the key and isables its use in the system
 179  *
 180  * @return 0 if successful \n
 181  *   FOSA_EINVAL The key is not initialised or is not in FOSA key range.
 182  **/
 183 int fosa_key_destroy(int key);
 184
 185
 186 /**
 187  * fosa_thread_set_specific_data()
 188  *
 189  * Set thread-specific data
 190  *
 191  * For the thread identified by tid, the thread-specifid data field
 192  * identified by key will be set to the value specified by value
 193  *
 194  * Returns 0 if successful; otherwise, an error code is returned
 195  *     EINVAL: the value of key is not between 0 and FOSA_MAX_KEYS-1
 196  *
 197  * Alternatively, in case of error the implementation is allowed to
 198  * notify it to the system console and then terminate the FRSH
 199  * implementation and dependant applications
 200  **/
 201  int fosa_thread_set_specific_data
 202        (int key, frsh_thread_id_t tid, const void * value);
 203
 204 /**
 205  * fosa_thread_get_specific_data()
 206  *
 207  * Get thread-specific data
 208  *
 209  * For the thread identified by tid, the thread-specifid data field
 210  * identified by key will be copied to the variable pointed to by value
 211  *
 212  * Returns 0 if successful; otherwise, an error code is returned
 213  *     EINVAL: the value of key is not between 0 and FOSA_MAX_KEYS-1
 214  *
 215  * Alternatively, in case of error the implementation is allowed to
 216  * notify it to the system console and then terminate the FRSH
 217  * implementation and dependant applications
 218  **/
 219 int fosa_thread_get_specific_data(int key, frsh_thread_id_t tid,
 220                                   void ** value);
 221
 222
 223 /******************************************************************
 224  * Thread scheduling
 225  *
 226  * This implementation of FRSH assumes an underlying fixed priority
 227  * scheduler with priorities in a range, with a minimum and a
 228  * maximumm, a number of priority levels with at least 31
 229  * priorities. A larger number implies a larger priority. In systems
 230  * in which the underlying scheduler uses the opposite convention, a
 231  * mapping is automatically provided by the OS adaptation layer.
 232  *******************************************************************/
 233
 234 /**
 235  * fosa_get_priority_max()
 236  *
 237  * Return the maximum priority value used in this implementation
 238  **/
 239 int fosa_get_priority_max();
 240
 241 /**
 242  * fosa_get_priority_min()
 243  *
 244  * Return the minimum priority value used in this implementation
 245  **/
 246 int fosa_get_priority_min();
 247
 248 /**
 249  * fosa_thread_attr_set_prio()
 250  *
 251  * Change the priority of a thread attributes object
 252  *
 253  * The priority of the thread attriutes object specified by attr is
 254  * set to the value specified by prio. This function has no runtime
 255  * effect on the priority, except when the attributes object is used
 256  * to create a thread, when it will be created with the specified
 257  * priority
 258  *
 259  * Returns 0 if successful, or the following error code:
 260  *    EINVAL: the specified priority value is not between the
 261  *            minimum and the maximum priorities defined in this
 262  *            FRSH implementation
 263  * Alternatively, in case of error the implementation is allowed to
 264  * notify it to the system console and then terminate the FRSH
 265  * implementation and dependant applications
 266  **/
 267 int fosa_thread_attr_set_prio(frsh_thread_attr_t *attr, int prio);
 268
 269 /**
 270  * fosa_thread_attr_get_prio()
 271  *
 272  * Get the priority from a thread attributes object
 273  *
 274  * This function sets the variable pointed to by prio to the
 275  * priority stored in the thread attributes object attr.
 276  *
 277  * Returns 0
 278  **/
 279  int fosa_thread_attr_get_prio
 280           (const frsh_thread_attr_t *attr, int *prio);
 281
 282 /**
 283  * fosa_thread_set_prio()
 284  *
 285  * Dynamically change the priority of a thread
 286  *
 287  * The priority of the thread identified by tid is
 288  * set to the value specified by prio.
 289  *
 290  * Returns 0 if successful, or the following error code:
 291  *    EINVAL: the specified priority value is not between the
 292  *            minimum and the maximum priorities defined in this
 293  *            FRSH implementation
 294  * Alternatively, in case of error the implementation is allowed to
 295  * notify it to the system console and then terminate the FRSH
 296  * implementation and dependant applications
 297  **/
 298 int fosa_thread_set_prio(frsh_thread_id_t tid, int prio);
 299
 300 /**
 301  * fosa_thread_get_prio()
 302  *
 303  * Dynamically get the priority of a thread
 304  *
 305  * This function sets the variable pointed to by prio to the
 306  * priority of the thread identified by tid
 307  *
 308  * Returns 0
 309  **/
 310 int fosa_thread_get_prio (frsh_thread_id_t tid, int *prio);
 311
 312
 313
 314 /*******************************************************************
 315  * Signals
 316  *
 317  * Signals represent events that may be notified by the system, or
 318  * sent explicitly by the application, and for which a thread may
 319  * synchronously wait. Signals carry an associated piece of
 320  * information (an integer or a pointer) and are queued until they are
 321  * accepted.  Signals are identified by an integer signal number (of
 322  * the type frsh_signal_t) in the range FOSA_SIGNAL_MIN,
 323  * FOSA_SIGNAL_MAX.  This range is required to have at least <tbd>
 324  * values.
 325  *******************************************************************/
 326
 327 /**
 328  * fosa_set_accepted_signals()
 329  *
 330  * Establish the set of signals that may be synchronously accepted
 331  * by the calling thread
 332  *
 333  * The function uses the array of signal numbers specified by set,
 334  * which must be of size equal to size
 335  *
 336  * Returns 0 if successful; otherwise it returns an error code:
 337  *     EINVAL: the array contains one or more values which are not
 338  *             between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
 339  *             is less than 0
 340  *
 341  * Alternatively, in case of error the implementation is allowed to
 342  * notify it to the system console and then terminate the FRSH
 343  * implementation and dependant applications
 344  **/
 345 int fosa_set_accepted_signals(frsh_signal_t set[], int size);
 346
 347 /**
 348  * fosa_signal_queue()
 349  *
 350  * Queue a signal
 351  *
 352  * This function is used to explicitly send a signal with a specified
 353  * value
 354  *
 355  * The signal number specified by signal is sent together with the
 356  * information specified by info, to the thread identified by
 357  * receiver. In those implementations that do not support queueing a
 358  * signal with information to a thread (such as POSIX), the signal may
 359  * be sent to any thread that is waiting for this signal via
 360  * fosa_signal_wait(). Portability can be ensured by having the receiver
 361  * thread be the one who is waiting for the signal.
 362  *
 363  * Returns 0 if successful; otherwise it returns an error code:
 364  *     EINVAL: the signal specified by signal is not
 365  *              between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX
 366  *
 367  *     EAGAIN: no resources are available to queue the signal; the
 368  *             maximum number of queued signals has been reached, or a
 369  *             systemwide resource limit has been exceeded
 370  *
 371  * Alternatively, in case of error the implementation is allowed to
 372  * notify it to the system console and then terminate the FRSH
 373  * implementation and dependant applications
 374  **/
 375 int fosa_signal_queue
 376        (frsh_signal_t signal, frsh_signal_info_t info,
 377         frsh_thread_id_t receiver);
 378
 379
 380 /**
 381  * fosa_signal_queue_scheduler()
 382  *
 383  * Queue a signal destinated to the scheduler
 384  *
 385  * This is a special case of fosa_signal_queue() in which the
 386  * destinator is the scheduler itself.  It is needed by the service
 387  * thread to notify the results to the scheduler.
 388  *
 389  * The problem with this case is that, depending on the implementation,
 390  * this call would be translated to a true signal or to a scheduler
 391  * notification message.
 392  *
 393  * Besides for the scheduler we don't have always a destinator
 394  * thread_id needed in frsh_signal_queue for OSE.
 395  *
 396  * So the fosa implementation will solve this issue internally.
 397  *
 398  * Returns 0 if successful; otherwise it returns an error code:
 399  *     EINVAL: the signal specified by signal is not
 400  *              between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX
 401  *
 402  *     EAGAIN: no resources are available to queue the signal; the
 403  *             maximum number of queued signals has been reached, or a
 404  *             systemwide resource limit has been exceeded
 405  *
 406  * Alternatively, in case of error the implementation is allowed to
 407  * notify it to the system console and then terminate the FRSH
 408  * implementation and dependant applications
 409  **/
 410 int fosa_signal_queue_scheduler(frsh_signal_t signal, frsh_signal_info_t info);
 411
 412
 413 /**
 414  * fosa_signal_wait()
 415  *
 416  * Wait for a signal
 417  *
 418  * The function waits for the arrival of one of the signals in the
 419  * array of signal numbers specified by set, which must be of size
 420  * equal to size. If there is a signal already queued, the function
 421  * returns immediately. If there is no signal of the specified set
 422  * queued, the calling thread is suspended until a signal from that
 423  * set arrives. Upon return, if signal_received is not NULL the number
 424  * of the signal received is stored in the variable pointed to by
 425  * signal_received; and if info is not NULL the associated information
 426  * is stored in the variable pointed to by info.
 427  *
 428  * Returns 0 if successful; otherwise it returns an error code:
 429  *     EINVAL: the array contains one or more values which are not
 430  *             between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
 431  *             is less than 0
 432  *
 433  * Alternatively, in case of error the implementation is allowed to
 434  * notify it to the system console and then terminate the FRSH
 435  * implementation and dependant applications
 436  **/
 437  int fosa_signal_wait
 438       (frsh_signal_t set[], int size, frsh_signal_t *signal_received,
 439        frsh_signal_info_t *info);
 440
 441 /**
 442  * fosa_signal_timedwait()
 443  *
 444  * Timed wait for a signal
 445  *
 446  * This function behaves the same as fosa_signal_wait(), except that
 447  * the suspension time is limited to the time interval specified in
 448  * the timespec structure referenced by timeout.
 449  *
 450  * Returns 0 if successful; otherwise it returns an error code:
 451  *     EINVAL: the array contains one or more values which are not
 452  *             between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
 453  *             is less than 0, or timeout is invalid
 454  *     EAGAIN: The timeout expired
 455  *
 456  * Alternatively, in case of the EINVAL error the implementation is
 457  * allowed to notify it to the system console and then terminate the
 458  * FRSH implementation and dependant applications
 459  **/
 460  int fosa_signal_timedwait
 461       (frsh_signal_t set[], int size, frsh_signal_t *signal_received,
 462        frsh_signal_info_t *info, const struct timespec *timeout);
 463
 464 /*}*/
 465
 466
 467 #endif      /* !FOSA_THREAD_AND_SIGNALS_H_ */