include/fosa_threads_and_signals.h

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