-// -----------------------------------------------------------------------
-// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+//----------------------------------------------------------------------
+// Copyright (C) 2006 - 2007 by the FRESCOR consortium:
//
// Universidad de Cantabria, SPAIN
// University of York, UK
// Visual Tools S.A. SPAIN
// Rapita Systems Ltd UK
// Evidence ITALY
-//
-// See http://www.frescor.org for a link to partners' websites
//
-// FRESCOR project (FP6/2005/IST/5-034026) is funded
+// See http://www.frescor.org
+//
+// The FRESCOR project (FP6/2005/IST/5-034026) is funded
// in part by the European Union Sixth Framework Programme
// The European Union is not liable of any use that may be
// made of this code.
//
-// This file is part of the FRSH implementation
//
-// FRSH is free software; you can redistribute it and/or modify
-// it under the terms of the GNU General Public License as published by
-// the Free Software Foundation; either version 2, or (at your option)
-// any later version.
+// based on previous work (FSF) done in the FIRST project
+//
+// Copyright (C) 2005 Mälardalen University, SWEDEN
+// Scuola Superiore S.Anna, ITALY
+// Universidad de Cantabria, SPAIN
+// University of York, UK
//
-// FRSH is distributed in the hope that it will be useful, but
-// WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-// General Public License for more details.
+// This file is part of FOSA (Frsh Operating System Abstraction)
//
-// You should have received a copy of the GNU General Public License
-// distributed with FRSH; see file COPYING. If not, write to the
-// Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
-// 02111-1307, USA.
+// FOSA is free software; you can redistribute it and/or modify it
+// under terms of the GNU General Public License as published by the
+// Free Software Foundation; either version 2, or (at your option) any
+// later version. FOSA is distributed in the hope that it will be
+// useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+// of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// General Public License for more details. You should have received a
+// copy of the GNU General Public License along with FOSA; see file
+// COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
+// Cambridge, MA 02139, USA.
//
-// As a special exception, if you include this header file into source
-// files to be compiled, this header file does not by itself cause
-// the resulting executable to be covered by the GNU General Public
-// License. This exception does not however invalidate any other
-// reasons why the executable file might be covered by the GNU General
-// Public License.
+// As a special exception, including FOSA header files in a file,
+// instantiating FOSA generics or templates, or linking other files
+// with FOSA objects to produce an executable application, does not
+// by itself cause the resulting executable application to be covered
+// by the GNU General Public License. This exception does not
+// however invalidate any other reasons why the executable file might be
+// covered by the GNU Public License.
// -----------------------------------------------------------------------
//fosa_thread_and_signals.h
//==============================================
#ifndef FOSA_THREAD_AND_SIGNALS_H_
#define FOSA_THREAD_AND_SIGNALS_H_
+#include "fosa_types.h"
+
+
+FOSA_CPP_BEGIN_DECLS
+
+
/**
* @defgroup threadandsignals Thread and Signals
* @ingroup fosa
*
- * This module defines the functions that manipulate frsh_threads and
- * frsh_signals inside FRSH implementation.
+ * This module defines the functions that manipulate fosa_threads and
+ * fosa_signals inside FRSH implementation.
*
* Applications can refer to FRSH threads but they cannot create them
* directly, instead they must use frsh_thread_create*() which in turn
* use fosa_thread_create().
*
* For signals, we assume that the OS provides a direct mapping
- * for frsh_signal_t and frsh_signal_info_t in the native interface.
+ * for fosa_signal_t and fosa_signal_info_t in the native interface.
*
* @{
**/
* Compare two thread identifiers to determine if they refer to the
* same thread
**/
-bool fosa_thread_equal(frsh_thread_id_t t1, frsh_thread_id_t t2);
+bool fosa_thread_equal(fosa_thread_id_t t1, fosa_thread_id_t t2);
/**
*
* Return the thread id of the calling thread
**/
-frsh_thread_id_t fosa_thread_self();
+fosa_thread_id_t fosa_thread_self();
+
+
+/*************************
+ * Thread attributes
+ *************************/
+
+/**
+ * fosa_thread_attr_init()
+ *
+ * Initialize a thread attributes object
+ *
+ * This function initializes the object pointed to by attr to all
+ * the default values defined by FRSH
+ *
+ * @return 0 if successful; otherwise it returns \n
+ * FOSA_ENOMEM: insufficient memory exists to initialize the thread
+ * attributes object
+ **/
+int fosa_thread_attr_init(fosa_thread_attr_t *attr);
+
+
+/**
+ * fosa_thread_attr_destroy()
+ *
+ * Destroy a thread attributes object
+ *
+ * This function is used to destroy the thread attributes object,
+ * pointed to by attr, and deallocate any system resources allocated for it
+ *
+ * Returns 0
+ */
+int fosa_thread_attr_destroy(fosa_thread_attr_t *attr);
+
+
+/**
+ * fosa_thread_attr_set_stacksize()
+ *
+ * Set the thread minimum stack size in a thread attributes object
+ *
+ * This function sets the minimum stack size of the thread attributes
+ * object attr to the value given by stacksize, in bytes. This
+ * function has no runtime effect on the stack size, except when the
+ * attributes object is used to create a thread, when it will be
+ * created with the specified minimum stack size
+ *
+ * @return 0 if successful, or the following error code:
+ * FOSA_EINVAL: the specified stacksize value is not supported in
+ * this implementation
+ */
+int fosa_thread_attr_set_stacksize(fosa_thread_attr_t *attr,
+ size_t stacksize);
+
+/**
+ * fosa_thread_attr_get_stacksize()
+ *
+ * Get the thread minimum stack size from a thread attributes object
+ *
+ * This function sets the variable pointed to by stacksize to the
+ * minimum stack size stored in the thread attributes object attr.
+ *
+ * @return 0
+ */
+int fosa_thread_attr_get_stacksize(const fosa_thread_attr_t *attr,
+ size_t *stacksize);
/*************************
*
* Returns 0 if successful; otherwise it returs a code error:
*
- * EAGAIN: the system lacks the necessary resources to create a
+ * FOSA_EAGAIN: the system lacks the necessary resources to create a
* new thread or the maximum number of threads has been
* reached
*
- * EINVAL: the value specified by attr is invalid (for instance,
+ * FOSA_EINVAL: the value specified by attr is invalid (for instance,
* it has not been correctly initialized)
*
- * EREJECT: the cretion of the thread was rejected by the frsh scheduler
+ * FOSA_EREJECT: the cretion of the thread was rejected by the frsh scheduler
* possibly because of incorrect attributes, or because the
* requested minimum capacity cannot be guaranteed
*
**/
int fosa_thread_create
- (frsh_thread_id_t *tid, const frsh_thread_attr_t *attr,
- frsh_thread_code_t code, void * arg);
+ (fosa_thread_id_t *tid, const fosa_thread_attr_t *attr,
+ fosa_thread_code_t code, void * arg);
/**
* Note: no thread termination primitive is provided. The termination
- * of a thread will be notifoed by the system to the FRSH scheduler
+ * of a thread will be notified by the system to the FRSH scheduler
* through the scheduler API
**/
* Create a new key for thread specific data.
*
* Prior to setting data in a key, we need ask the system to create
- * one for us.
+ * one for us. The thread specific data of all the threads is set to
+ * the value NULL until changed to a different value via
+ * fosa_thread_set_specific_data().
*
* @return 0 if successful \n
* FOSA_EINVAL If we already have reached the FOSA_MAX_KEYS limit.
*
* Destroy a key
*
- * This destroys the key and isables its use in the system
+ * This destroys the key and disables its use in the system
*
* @return 0 if successful \n
* FOSA_EINVAL The key is not initialised or is not in FOSA key range.
* identified by key will be set to the value specified by value
*
* Returns 0 if successful; otherwise, an error code is returned
- * EINVAL: the value of key is not between 0 and FOSA_MAX_KEYS-1
+ * FOSA_EINVAL: the value of key is not between 0 and FOSA_MAX_KEYS-1
*
* Alternatively, in case of error the implementation is allowed to
* notify it to the system console and then terminate the FRSH
* implementation and dependant applications
**/
int fosa_thread_set_specific_data
- (int key, frsh_thread_id_t tid, const void * value);
+ (int key, fosa_thread_id_t tid, const void * value);
/**
* fosa_thread_get_specific_data()
* identified by key will be copied to the variable pointed to by value
*
* Returns 0 if successful; otherwise, an error code is returned
- * EINVAL: the value of key is not between 0 and FOSA_MAX_KEYS-1
+ * FOSA_EINVAL: the value of key is not between 0 and FOSA_MAX_KEYS-1
*
* Alternatively, in case of error the implementation is allowed to
* notify it to the system console and then terminate the FRSH
* implementation and dependant applications
**/
-int fosa_thread_get_specific_data(int key, frsh_thread_id_t tid,
+int fosa_thread_get_specific_data(int key, fosa_thread_id_t tid,
void ** value);
* priority
*
* Returns 0 if successful, or the following error code:
- * EINVAL: the specified priority value is not between the
+ * FOSA_EINVAL: the specified priority value is not between the
* minimum and the maximum priorities defined in this
* FRSH implementation
* Alternatively, in case of error the implementation is allowed to
* notify it to the system console and then terminate the FRSH
* implementation and dependant applications
**/
-int fosa_thread_attr_set_prio(frsh_thread_attr_t *attr, int prio);
+int fosa_thread_attr_set_prio(fosa_thread_attr_t *attr, int prio);
/**
* fosa_thread_attr_get_prio()
* Returns 0
**/
int fosa_thread_attr_get_prio
- (const frsh_thread_attr_t *attr, size_t *prio);
+ (const fosa_thread_attr_t *attr, int *prio);
/**
* fosa_thread_set_prio()
* set to the value specified by prio.
*
* Returns 0 if successful, or the following error code:
- * EINVAL: the specified priority value is not between the
+ * FOSA_EINVAL: the specified priority value is not between the
* minimum and the maximum priorities defined in this
* FRSH implementation
* Alternatively, in case of error the implementation is allowed to
* notify it to the system console and then terminate the FRSH
* implementation and dependant applications
**/
-int fosa_thread_set_prio(frsh_thread_id_t tid, int prio);
+int fosa_thread_set_prio(fosa_thread_id_t tid, int prio);
/**
* fosa_thread_get_prio()
*
* Returns 0
**/
-int fosa_thread_get_prio (frsh_thread_id_t tid, int *prio);
+int fosa_thread_get_prio (fosa_thread_id_t tid, int *prio);
* synchronously wait. Signals carry an associated piece of
* information (an integer or a pointer) and are queued until they are
* accepted. Signals are identified by an integer signal number (of
- * the type frsh_signal_t) in the range FOSA_SIGNAL_MIN,
+ * the type fosa_signal_t) in the range FOSA_SIGNAL_MIN,
* FOSA_SIGNAL_MAX. This range is required to have at least <tbd>
* values.
*******************************************************************/
* which must be of size equal to size
*
* Returns 0 if successful; otherwise it returns an error code:
- * EINVAL: the array contains one or more values which are not
+ * FOSA_EINVAL: the array contains one or more values which are not
* between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
* is less than 0
*
* notify it to the system console and then terminate the FRSH
* implementation and dependant applications
**/
-int fosa_set_accepted_signals(frsh_signal_t set[], int size);
+int fosa_set_accepted_signals(fosa_signal_t set[], int size);
/**
* fosa_signal_queue()
* thread be the one who is waiting for the signal.
*
* Returns 0 if successful; otherwise it returns an error code:
- * EINVAL: the signal specified by signal is not
+ * FOSA_EINVAL: the signal specified by signal is not
* between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX
*
- * EAGAIN: no resources are available to queue the signal; the
+ * FOSA_EAGAIN: no resources are available to queue the signal; the
* maximum number of queued signals has been reached, or a
* systemwide resource limit has been exceeded
*
* notify it to the system console and then terminate the FRSH
* implementation and dependant applications
**/
- int fosa_signal_queue
- (frsh_signal_t signal, frsh_signal_info_t info,
- frsh_thread_id_t receiver);
+int fosa_signal_queue
+ (fosa_signal_t signal, fosa_signal_info_t info,
+ fosa_thread_id_t receiver);
+
+
/**
* is stored in the variable pointed to by info.
*
* Returns 0 if successful; otherwise it returns an error code:
- * EINVAL: the array contains one or more values which are not
+ * FOSA_EINVAL: the array contains one or more values which are not
* between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
* is less than 0
*
* implementation and dependant applications
**/
int fosa_signal_wait
- (frsh_signal_t set[], int size, frsh_signal_t *signal_received,
- frsh_signal_info_t *info);
+ (fosa_signal_t set[], int size, fosa_signal_t *signal_received,
+ fosa_signal_info_t *info);
/**
* fosa_signal_timedwait()
* the timespec structure referenced by timeout.
*
* Returns 0 if successful; otherwise it returns an error code:
- * EINVAL: the array contains one or more values which are not
+ * FOSA_EINVAL: the array contains one or more values which are not
* between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
* is less than 0, or timeout is invalid
- * EAGAIN: The timeout expired
+ * FOSA_EAGAIN: The timeout expired
*
- * Alternatively, in case of the EINVAL error the implementation is
+ * Alternatively, in case of the FOSA_EINVAL error the implementation is
* allowed to notify it to the system console and then terminate the
* FRSH implementation and dependant applications
**/
int fosa_signal_timedwait
- (frsh_signal_t set[], int size, frsh_signal_t *signal_received,
- frsh_signal_info_t *info, const struct timespec *timeout);
+ (fosa_signal_t set[], int size, fosa_signal_t *signal_received,
+ fosa_signal_info_t *info, const struct timespec *timeout);
/*}*/
+FOSA_CPP_END_DECLS
#endif /* !FOSA_THREAD_AND_SIGNALS_H_ */
projects / frescor / fosa.git / blobdiff