include/fosa_threads_and_signals.h

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