frsh_aquosa/core.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. 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
  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 FRSH API
  35 //
  36 //  FRSH API is free software; you can  redistribute it and/or  modify
  37 //  it under the terms of  the GNU General Public License as published by
  38 //  the Free Software Foundation;  either  version 2, or (at  your option)
  39 //  any later version.
  40 //
  41 //  FRSH API  is distributed  in  the hope  that  it  will  be useful,  but
  42 //  WITHOUT  ANY  WARRANTY;     without  even the   implied   warranty  of
  43 //  MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR PURPOSE. See  the  GNU
  44 //  General Public License for more details.
  45 //
  46 //  You should have  received a  copy of  the  GNU  General Public License
  47 //  distributed  with  FRSH API;  see file COPYING.   If not,  write to the
  48 //  Free Software  Foundation,  59 Temple Place  -  Suite 330,  Boston, MA
  49 //  02111-1307, USA.
  50 //
  51 //  As a special exception, if you include this header file into source
  52 //  files to be compiled, this header file does not by itself cause
  53 //  the resulting executable to be covered by the GNU General Public
  54 //  License.  This exception does not however invalidate any other
  55 //  reasons why the executable file might be covered by the GNU General
  56 //  Public License.
  57 // -----------------------------------------------------------------------
  58 //==============================================
  59 //  ******** *******    ********  **      **
  60 //  **///// /**////**  **//////  /**     /**
  61 //  **      /**   /** /**        /**     /**
  62 //  ******* /*******  /********* /**********
  63 //  **////  /**///**  ////////** /**//////**
  64 //  **      /**  //**        /** /**     /**
  65 //  **      /**   //** ********  /**     /**
  66 //  //       //     // ////////   //      //
  67 //
  68 // FRSH(FRescor ScHeduler), pronounced "fresh"
  69 //==============================================
  70 #ifndef CORE_H
  71 #define CORE_H
  72
  73 /*
  74  * frsh_init(), initialize FRSH for the calling process
  75  *
  76  * Must be called before starting using the framework.
  77  * No FRSH call will be successful if this routine is not invoked
  78  *
  79  * Note that no BACKGROUND is created and negotiated and the caller thread
  80  * is bound to no BACKGROUND vres, since no way is provided in order of
  81  * specifying the contract label and get back the vres id!
  82  *
  83  * Note also that, since in this implementation the threads/processes with
  84  * backgound contracts are left into the default Linux scheduler hands' and
  85  * not attached to any AQuoSA server, while we're violating what D-AC2v1
  86  * (pag. 14) says, we achieve exactly the same behaviour!!
  87  *
  88  * possible return values:
  89  *  FRSH_NO_ERROR
  90  *  FRSH_ERR_ALREADY_INITIALIZED
  91  *  FRSH_ERR_INTERNAL_ERROR (something, different from the previous case, gone wrong)
  92  */
  93
  94 /* forward declarations, see below ... */
  95 int frsh_aquosa_init();
  96
  97 /*
  98  * frsh_thread_bind(), bind a thread to a vres
  99  *
 100  * Asks the service thread for binding of a thread to a valid, REGULAR and
 101  * contracetd vres.
 102  * If all is ok the thread is attached to an AQuoSA resource reservation server
 103  *
 104  * As usual the code below simply prepares a message, send it and wait for
 105  * the answer from the service thread, for details on the implementation check
 106  * 'bind_thread()' in the frsh_service_th.c source file
 107
 108  * possible return values:
 109  *  FRSH_NO_ERROR
 110  *  FRSH_ERR_NOT_INITIALIZED
 111  *  FRSH_BAD_ARGUMENT(*) (invalid or dummy vres)
 112  *  FRSH_ERR_NOT_CONTRACTED_VRES(*)
 113  *  FRSH_ERR_ALREADY_BOUND(*)
 114  *  FRSH_ERR_INTERNAL_ERROR(*) (something wrong with AQuoSA or with the service thread internal data structures)
 115  *  FRSH_ERR_INVALID_SCHEDULER_REPLY (error in communication with the service thread)
 116  */
 117 int frsh_thread_bind(const frsh_vres_id_t vres, const frsh_thread_id_t thread);
 118
 119 /*
 120  * frsh_thread_unbind(), unbind a thread from a vres
 121  *
 122  * Asks the service thread for revoke the binding of a thread to a its actual
 123  * vres.
 124  * If all is ok the thread is detached from the AQuoSA resource
 125  * reservation server.
 126  *
 127  * The code below only prepares the message, send it and wait for the answer,
 128  * for details on the implementation check 'unbind_thread()' in the
 129  * frsh_service_th.c source file
 130  *
 131  * possible return values:
 132  *  FRSH_NO_ERROR
 133  *  FRSH_ERR_NOT_INITIALIZED
 134  *  FRSH_BAD_ARGUMENT(*) (invalid thread)
 135  *  FRSH_ERR_NOT_BOUND(*)
 136  *  FRSH_ERR_INTERNAL_ERROR(*) (something wrong with AQuoSA or with the service thread internal data structures)
 137  *  FRSH_ERR_INVALID_SCHEDULER_REPLY (error in communication with the service thread)
 138  */
 139 int frsh_thread_unbind(const frsh_thread_id_t thread);
 140
 141 /*
 142  * API call for 'frsh_thread_create_and_bind()', as said prepares the
 143  * wrapper code argument data structure, create the new thread and wait
 144  * its acknowledgment before stepping over
 145  *
 146  * possible return values:
 147  *  FRSH_NO_ERROR
 148  *  FRSH_ERR_NOT_INITIALIZED
 149  *  FRSH_ERR_BAD_ARGUMENT (NULL thread or thread_code)
 150  *  whatever 'fosa_thread_create()' returns
 151  *  FRSH_ERR_INTERNAL_ERROR (something wrong in signal handling)
 152  */
 153 int frsh_thread_create_and_bind(const frsh_vres_id_t vres,
 154         frsh_thread_id_t *thread,
 155         frsh_thread_attr_t *attr,
 156         frsh_thread_code_t thread_code,
 157         void *arg);
 158
 159 /*
 160  * API call for 'frsh_thread_create_in_background()', as said creates a
 161  * background contract and negotiate it (we know they're always accepted
 162  * but we need to get the service thread account fo the new vres), then
 163  * create the new thread, exactly as seen in 'frsh_thread_create_and_bind()'
 164  * and wait for its acknowledgment
 165  *
 166  * possible return values:
 167  *  FRSH_NO_ERROR
 168  *  FRSH_ERR_NOT_INITIALIZED
 169  *  FRSH_ERR_BAD_ARGUMENT (NULL thread_id, thread_code, contract_label or vres_id)
 170  *  FRSH_ERR_TOO_MANY_VRES(*)
 171  *  FRSH_ERR_CONTRACT_ID_ALREADY_EXISTS(*)
 172  *  FRSH_ERR_CONTRACT_REJECTED(*)
 173  *  whatever 'fosa_thread_create()' returns
 174  *  FRSH_ERR_INTERNAL_ERROR(*) (something wrong with AQuoSA or with the service thread internal data structures)
 175  *  FRSH_ERR_INTERNAL_ERROR (something wrong in signal handling)
 176  */
 177 int frsh_thread_create_in_background(frsh_thread_code_t thread_code,
 178         const void *thread_arg,
 179         const frsh_contract_label_t contract_label,
 180         frsh_thread_attr_t *attr,
 181         frsh_thread_id_t *thread_id,
 182         frsh_vres_id_t *vres_id);
 183
 184 #endif /* CORE_H */