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