HLT/BASE/interface/AliHLTExternalInterface.h

   1 // $Id$
   2
   3 #ifndef ALIHLT_EXTERNALINTERFACE_H
   4 #define ALIHLT_EXTERNALINTERFACE_H
   5 //* This file is property of and copyright by the ALICE HLT Project        *
   6 //* ALICE Experiment at CERN, All rights reserved.                         *
   7 //* See cxx source for full Copyright notice                               *
   8
   9 /** @file   AliHLTExternalInterface.h
  10     @author Matthias Richter, Timm Steinbeck
  11     @date
  12     @brief  Pure and dynamic C interface to the AliRoot HLT analysis
  13     @note   Utilized by the HLT Online (PubSub) framework
  14 */
  15
  16 /**
  17  * @defgroup alihlt_wrapper_interface The HLT wrapper interface
  18  * The wrapper interface is a pure C interface which allows to use the
  19  * analysis components in external applications. The interface is utilized
  20  * to bind the analysis code to the PubSub framework.
  21  *
  22  * \image html PubSub_WrapperComponent.png "Wrapper interface"
  23  *
  24  * @section alihlt_wrapper_interface_general Interface functions
  25  * The interface is based on function signatures. The function
  26  * AliHLTAnalysisGetInterfaceCall(const char* signature) of type
  27  * AliHLTAnalysisFctGetInterfaceCall looks for a matching interface
  28  * function and returns the pointer if it is found.
  29  * @ref ALIHLTANALYSIS_FCT_GETINTERFACECALL defines the function name.
  30  *
  31  * @section alihlt_wrapper_interface_usage Usage
  32  * @subsection alihlt_wrapper_interface_usage_systemcalls Getting the interface functions
  33  * <pre>
  34  * string libraryPath=ALIHLTANALYSIS_INTERFACE_LIBRARY;
  35  *
  36  * string libraryPath=gBasePath;
  37  * libraryPath+="/";
  38  * libraryPath+=ALIHLTANALYSIS_INTERFACE_LIBRARY;
  39  *
  40  * void* libHandle=dlopen(libraryPath.c_str(), RTLD_NOW);
  41  * if (!libHandle) {
  42  *   cerr << "error: can not load library " << libraryPath.c_str() << endl;
  43  *   return -1;
  44  * }
  45  *
  46  * AliHLTAnalysisFctGetInterfaceCall fctGetSystemCall=(AliHLTAnalysisFctGetInterfaceCall)dlsym(libHandle, ALIHLTANALYSIS_FCT_GETINTERFACECALL);
  47  * if (!fctGetSystemCall) {
  48  *   cerr << "error: can not find function '" << ALIHLTANALYSIS_FCT_GETINTERFACECALL << "' in " << libraryPath.c_str() << endl;
  49  *   return -1;
  50  * }
  51  *
  52  * </pre>
  53  *
  54  * @subsection alihlt_wrapper_interface_usage_init System initialization
  55  * <pre>
  56  * AliHLTAnalysisEnvironment environment;
  57  * memset(&environment, 0, sizeof(environment));
  58  *
  59  * // setting function pointers
  60  * environment.fStructSize=sizeof(environment);
  61  * environment.fAllocMemoryFunc=AllocMemory;
  62  * environment.fLoggingFunc=Logging;
  63  *
  64  * AliHLTExtFctInitSystem fctInitSystem=(AliHLTExtFctInitSystem)fctGetSystemCall("int AliHLTAnalysisInitSystem(unsigned long,AliHLTAnalysisEnvironment*,unsigned long,const char*)");
  65  * if (!fctInitSystem) {
  66  *   cerr << "error: missing AliHLTAnalysisInitSystem call" << endl;
  67  *   return -1;
  68  * }
  69  *
  70  * if ((iResult=fctInitSystem( ALIHLT_DATA_TYPES_VERSION, &environment, 0xbeef, "dummy-run" ))<0) {
  71  *   cerr << "InitSystem failed with " << iResult << endl;
  72  *   return iResult;
  73  * }
  74  *
  75  * </pre>
  76  *
  77  * @subsection alihlt_wrapper_interface_usage_create Load library and create component
  78  * <pre>
  79  * AliHLTExtFctLoadLibrary fctLoadLibrary=(AliHLTExtFctLoadLibrary)fctGetSystemCall("int AliHLTAnalysisLoadLibrary(const char*)");
  80  * if (!fctLoadLibrary) {
  81  *   cerr << "error: missing LoadLibrary call" << endl;
  82  *   return -1;
  83  * }
  84  *
  85  * if ((iResult=fctLoadLibrary(moduleLibrary))<0) {
  86  *   cerr << "error: AliHLTAnalysisLoadLibrary failed with " << iResult << endl;
  87  *   return iResult;
  88  * }
  89  *
  90  * AliHLTExtFctCreateComponent fctCreateComponent=(AliHLTExtFctCreateComponent)fctGetSystemCall("int AliHLTAnalysisCreateComponent(const char*,void*,int,const char**,AliHLTComponentHandle*,const char*)");
  91  * if (!fctCreateComponent) {
  92  *   cerr << "error: missing CreateComponent call" << endl;
  93  *   return -1;
  94  * }
  95  *
  96  * AliHLTComponentHandle handle;
  97  * if ((iResult=fctCreateComponent("TestProcessor", &gDummy, 0, NULL, &handle, "-chainid=test" ))<0) {
  98  *   cerr << "error: AliHLTAnalysisCreateComponent failed with " << iResult << endl;
  99  *   return iResult;
 100  * }
 101  *
 102  * </pre>
 103  *
 104  * @section alihlt_wrapper_interface_cdb CDB handling
 105  * The interface initializes the CDB from the path found
 106  * in the environment variable ALIHLT_HCDBDIR. If this is empty, path is
 107  * set from <tt>$ALICE_ROOT</tt>.
 108  */
 109
 110 /////////////////////////////////////////////////////////////////////////////////////
 111 //
 112 // AliHLT external interface functions
 113 //
 114
 115 #ifdef __cplusplus
 116 extern "C" {
 117 #endif
 118
 119   /**
 120    * Get a system call of the interface.
 121    * @param function signature
 122    * @return pointer to system call
 123    * @ingroup alihlt_wrapper_interface
 124    */
 125   void* AliHLTAnalysisGetInterfaceCall(const char* function);
 126
 127 #ifdef __cplusplus
 128 }
 129 #endif
 130
 131
 132 /////////////////////////////////////////////////////////////////////////////////////
 133 //
 134 // AliHLTSystem interface functions
 135 //
 136
 137 class AliHLTSystem;
 138 class AliHLTOUT;
 139 class AliESDEvent;
 140
 141 #ifdef __cplusplus
 142 extern "C" {
 143 #endif
 144
 145 /**
 146  * Set options for an AliHLTSystem instance.
 147  * The function is introduced for the sake of backward compatibility.
 148  * Called from AliHLTReconstructor, which loads the function dynamically.
 149  * @return neg. error code if failed                                     <br>
 150  *         -EFAULT    type cast failed                                   <br>
 151  *         -EINVAL    invalid parameter
 152  * @ingroup alihlt_system_interface
 153  */
 154 int AliHLTSystemSetOptions(AliHLTSystem*, const char*);
 155
 156 /**
 157  * Process the HLTOUT data with the specified system instance.
 158  * The function is introduced for the sake of backward compatibility.
 159  * Called from AliHLTReconstructor, which loads the function dynamically.
 160  * @return neg. error code if failed                                     <br>
 161  *         -EFAULT    type cast failed                                   <br>
 162  *         -EINVAL    invalid parameter
 163  * @ingroup alihlt_system_interface
 164  */
 165 int AliHLTSystemProcessHLTOUT(AliHLTSystem* pInstance, AliHLTOUT* pHLTOUT, AliESDEvent* esd);
 166
 167 #ifdef __cplusplus
 168 }
 169 #endif
 170
 171 #endif //ALIHLT_EXTERNALINTERFACE_H