1 //----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2007 by the FRESCOR consortium:
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
11 // Thales Communication S.A. FRANCE
12 // Visual Tools S.A. SPAIN
13 // Rapita Systems Ltd UK
16 // See http://www.frescor.org
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
24 // based on previous work (FSF) done in the FIRST project
26 // Copyright (C) 2005 Mälardalen University, SWEDEN
27 // Scuola Superiore S.Anna, ITALY
28 // Universidad de Cantabria, SPAIN
29 // University of York, UK
31 // This file is part of FOSA (Frsh Operating System Abstraction)
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.
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 // -----------------------------------------------------------------------
53 //==============================================
54 // ******** ****** ******** **********
55 // **///// /** ** **////// /** /**
56 // ** /** ** /** /** /**
57 // ******* /** ** /********* /**********
58 // **//// /** ** ////////** /**//////**
59 // ** /** ** /** /** /**
60 // ** /** ** ******** /** /**
61 // // /******/ //////// // //
63 // FOSA(Frescor Operating System Adaptation layer)
64 //================================================
67 #ifndef FOSA_LONG_JUMP
68 #define FOSA_LONG_JUMP
70 #include "fosa_types.h"
71 #include "fosa_opaque_types.h"
76 * @defgroup longjumps Long Jumps
79 * This module defines the types and functions that allow te
80 * application to abort a piece of running code; it can be used to
81 * stop an action that is overrunning its budget and needs to be
82 * aborted, without aborting the whole thread on which it is based.
84 * The model is that the application installs a long-jump handler for
85 * each thread that potentially needs to be aborted through the long
86 * jump mechanism. As a result of installing the handler it gets back
87 * a signal identifier. This signal is later used to notify the
88 * handler that the thread needs to be aborted. Previous to sending
89 * the signal, the application must store the context of the thread so
90 * that when it is aborted the saved context can be recovered. The
91 * signal may be sent to the handler from any thread, but must contain
92 * as attached information a pointer to the variable where the context
95 * The implementation may internally choose to implement a single long
96 * jump handler for all threads (and use a single signal), or one for each
97 * thread (requiring the reservation of a pool of signals).
104 /*************************
106 *************************/
109 * fosa_long_jump_save_context
111 * Save the context of the current thread for a future long jump
113 * This function stores in context the information required to modify
114 * the stack of the calling thread so that a later long jump may be
115 * executed in the future to restore this context
117 * This function stores in 'context' the thread id, the registers,
118 * and the stack frame of the calling thread. This information can be
119 * used by the long jump handler to change the stack of the task so
120 * that when it is scheduled again it returns to the end of this
124 * Returns 0 if successful; otherwise it returns an error code:
125 * FOSA_EINVAL: the value of context is invalid
127 * Alternatively, in case of error the implementation is allowed to
128 * notify it to the system console and then terminate the FRSH
129 * implementation and dependant applications
131 int fosa_long_jump_save_context
132 (fosa_long_jump_context_t * context);
136 * fosa_long_jump_was_performed
138 * Check whether the current thread suffered a long jump or not
140 * This function should be invoked after fosa_long_jump_save_context
141 * to determine whether the current thread is executing normally, or
142 * has suffered a long jump to the point where the context was
143 * saved. If invoked after a direct invocation to
144 * fosa_long_jump_save_context, the function shall set the variable
145 * pointed to by jumped to zero. If invoked after returning from
146 * fosa_long_jump_save_context due to a long jump caused by the long
147 * jump handler, the function shall set this variable to 1.
149 * Returns 0 if successful; otherwise it returns an error code:
150 * FOSA_EINVAL: the value of context is invalid
152 * Alternatively, in case of error the implementation is allowed to
153 * notify it to the system console and then terminate the FRSH
154 * implementation and dependant applications
156 int fosa_long_jump_was_performed
157 (const fosa_long_jump_context_t * context, int * jumped);
161 * fosa_long_jump_install_handler
163 * Install a long jump handler for the calling thread
165 * This function shall install a handler that is capable of causing a
166 * long jump operation that restores the context of a thread to a
167 * previously saved value. If the handler has already been installed
168 * for this thread the previously installed handler will be used and
169 * the call shall succeed.
171 * The long-jump handler is waiting for a signal to notify that a
172 * thread context should be restored. This signal must carry attached
173 * to it a pointer to the variable where the thread context was
174 * saved. The thread referenced in that context will have its
175 * internal context restored to the point where it was saved. For
176 * this restore operation to work properly, the program frame where
177 * the thread saved its context must still be valid.
179 * Depending on the implementation a given thread may also install a signal
180 * handler or a signal handler thread that is capable of executing
181 * the actions required to restore the context of a thread from the
182 * appropriate context. For instance, in POSIX it is necesaray that
183 * the context is restored from the same thread being restored,
184 * usually from a signal handler of that thread.
186 * The function shall store in the variable pointed to by signal the
187 * identifier of the signal that must be used to notify the request
188 * for a long jump to be executed. In the variable pointed to by
189 * handler, it shall store the thread id to which the signal must be
190 * sent. The signal must be sent with its attached information set to
191 * a pointer to the variable of type fosa_long_jump_context_t where
192 * the context of the thread to be restored was saved.
194 * Returns 0 if successful; otherwise it returns an error code:
195 * FOSA_EINVAL: the value of context is invalid
196 * FOSA_ENOMEM: there are no resources to satisfy the call at this time
198 * Alternatively, in case of error the implementation is allowed to
199 * notify it to the system console and then terminate the FRSH
200 * implementation and dependant applications
202 int fosa_long_jump_install_handler
203 (fosa_signal_t *signal, fosa_thread_id_t *handler);
212 #endif /* !FOSA_LONG_JUMP */