00001 #ifndef __XRDOLBXMI_H__ 00002 #define __XRDOLBXMI_H__ 00003 /******************************************************************************/ 00004 /* */ 00005 /* X r d O l b X m i . h h */ 00006 /* */ 00007 /* (c) 2006 by the Board of Trustees of the Leland Stanford, Jr., University */ 00008 /* All Rights Reserved */ 00009 /* Produced by Andrew Hanushevsky for Stanford University under contract */ 00010 /* DE-AC02-76-SFO0515 with the Department of Energy */ 00011 /******************************************************************************/ 00012 00013 #include <sys/types.h> 00014 00015 #include "XrdOlb/XrdOlbReq.hh" 00016 00017 /* 00018 The XrdOlbXmi class defines the interface the olbd uses to an external 00019 manager. When the olb.xmilib directive is specified, the olbd loads the 00020 plugin using XrdOlbgetXmi() to instantiate the plugin objects, as explained 00021 after the definition of the abstract class. The olbd then uses the Xmi 00022 defined methods to process certain requests instead of it's own default 00023 methods. As the Xmi interface runs synchronously with respect to being called, 00024 it should dispatch any long work to another thread to allow the next request 00025 to be processed by the plugin. You should use the thread scheduler passed 00026 via the XrdOlbXmiEnv structure (see below). 00027 00028 Each method (other that Prep(), see below) is passed an XrdOlbReq object. 00029 This object must be used to send a reply to the client (only one reply is 00030 allowed). A reply is *mandatory* if the function returns TRUE; even if that 00031 reply is merely an indication that everything succeeded. A reply must *not* 00032 be sent if the function returns FALSE; as a reply will be sent by the driver. 00033 Refer to XrdOlbReq.hh on the description of how replies are effected. 00034 00035 The Prep() method is a background function and the client never expects a 00036 reply. Therefore, no request object is passed since no reply is possible. 00037 Instead, the first parameter is a request ID that is used to tag the 00038 request. This ID may be passed later with XMI_CANCEL set to cancel and 00039 path passed as a null string. All preparation for files tagged with request 00040 ID should be stopped, if possible. 00041 00042 The Xmi methods may be called in one of two modes, DIRECT or INDIRECT. 00043 The modes are indicated by XeqMode(). In DIRECT mode the Xmi methods are 00044 called synchronously. In INDIRECT mode, the Xmi methods are given thread as 00045 well as client isolation by the olbd using an asynchronous encapsulated 00046 callback mechanism. Normally, INDIRECT mode should be used. The 00047 implementation is not particularly relevant as the protocol details are 00048 handled by the Xmi driver and the request object. 00049 00050 Each method must return either true (1) or false (0). However, the action 00051 taken based on the return value depends on the calling mode. 00052 00053 TRUE (1) -> The function was processed and a reply was sent. 00054 Action: INDIRECT: Normal processing continues, the request was done. 00055 DIRECT: Same as above. 00056 FALSE (0) -> The function was *not* processed and *no* reply was sent. 00057 Action: INDIRECT: An error reply is sent and processing continues. 00058 DIRECT: Processing continues as if the Xmi was not present. 00059 00060 See the description of XeqMode() on how to indicate which methods are to 00061 be called and which mode each method requires. 00062 */ 00063 00064 /******************************************************************************/ 00065 /* X r d O l b X m i E n v */ 00066 /******************************************************************************/ 00067 00068 /* The XrdOlbXmiEnv structure is passed to XrdOlbgetXmi() and contains 00069 information that may be relevant to the Xmi object. The information is 00070 static in that it persists during the execution of the program. 00071 */ 00072 00073 class XrdSysError; 00074 class XrdInet; 00075 class XrdScheduler; 00076 class XrdOucName2Name; 00077 class XrdOucTrace; 00078 00079 struct XrdOlbXmiEnv 00080 { 00081 const char *Role; // Manager | Peer | Proxy | Supervisor | Server 00082 const char *ConfigFN; // -> Config file name 00083 const char *Parms; // -> Optional parms from xmilib directive 00084 XrdSysError *eDest; // -> Error message handler 00085 XrdInet *iNet; // -> Network object 00086 XrdScheduler *Sched; // -> Thread scheduler 00087 XrdOucTrace *Trace; // -> Trace handler 00088 XrdOucName2Name *Name2Name; // -> lfn to xxx mapper (may be null) 00089 }; 00090 00091 /******************************************************************************/ 00092 /* X r d O l b X m i */ 00093 /******************************************************************************/ 00094 00095 class XrdOlbPrepArgs; 00096 00097 // Flags passed to Prep(): XMI_RW, XMI_CANCEL 00098 // Flags passed to Select(): XMI_RW, XMI_NEW, XMI_TRUNC 00099 // 00100 #define XMI_RW 0x0001 00101 #define XMI_NEW 0x0002 00102 #define XMI_TRUNC 0x0004 00103 #define XMI_CANCEL 0x0008 00104 #define XMI_LOCATE 0x0010 00105 00106 // Flags to be passed back by XeqMode() 00107 // 00108 #define XMI_CHMOD 0x00000001 00109 #define XMI_LOAD 0x00000002 00110 #define XMI_MKDIR 0x00000004 00111 #define XMI_MKPATH 0x00000008 00112 #define XMI_PREP 0x00000010 00113 #define XMI_RENAME 0x00000020 00114 #define XMI_REMDIR 0x00000040 00115 #define XMI_REMOVE 0x00000080 00116 #define XMI_SELECT 0x00000100 00117 #define XMI_SPACE 0x00000200 00118 #define XMI_STAT 0x00000400 00119 #define XMI_ALL 0x000007ff 00120 00121 class XrdOlbXmi 00122 { 00123 public: 00124 00125 // Called when trying to change the mode of a file 00126 // 00127 virtual int Chmod ( XrdOlbReq *Request, 00128 const char *path, 00129 mode_t mode) = 0; 00130 00131 // Called when trying to determine the load on this host (not yet implemented) 00132 // 00133 virtual int Load ( XrdOlbReq *Request) {return 0;} // Server only 00134 00135 // Called to make a directory 00136 // 00137 virtual int Mkdir ( XrdOlbReq *Request, 00138 const char *path, 00139 mode_t mode) = 0; 00140 00141 // Called to make a directory path 00142 // 00143 virtual int Mkpath( XrdOlbReq *Request, 00144 const char *path, 00145 mode_t mode) = 0; 00146 00147 // Called to prepare future access to a file 00148 // 00149 virtual int Prep (const char *ReqID, 00150 const char *Path, 00151 int Opts) = 0; 00152 // Called to rename a file or directory 00153 // 00154 virtual int Rename( XrdOlbReq *Request, 00155 const char *oldpath, 00156 const char *newpath) = 0; 00157 00158 // Called to remove a directory 00159 // 00160 virtual int Remdir( XrdOlbReq *Request, 00161 const char *path) = 0; 00162 00163 // Called to remove a file 00164 // 00165 virtual int Remove( XrdOlbReq *Request, 00166 const char *path) = 0; 00167 00168 // Called when a client attempts to open a file. The opts indicate how the 00169 // file will used and whether it is to be created. 00170 // 00171 virtual int Select( XrdOlbReq *Request, // See description above 00172 const char *path, 00173 int opts) = 0; 00174 00175 // Called to determine how much space exists in this server (not implemented) 00176 // 00177 virtual int Space ( XrdOlbReq *Request) {return 0;} // Server Only 00178 00179 // Called to get information about a file 00180 // 00181 virtual int Stat ( XrdOlbReq *Request, 00182 const char *path) = 0; 00183 00184 // Called after the plugin is loaded to determine which and how the above 00185 // methods are to be called. 00186 // 00187 virtual void XeqMode(unsigned int &isNormal, 00188 unsigned int &isDirect) 00189 {isNormal = XMI_LOAD | XMI_SPACE; isDirect = 0;} 00190 00191 XrdOlbXmi() {} 00192 virtual ~XrdOlbXmi() {} 00193 }; 00194 00195 /* 00196 The XrdOlbXmi object is intended to be supplied as a plugin from a shared 00197 library. This library is identified by the "olb.xmilib" directive. When 00198 the library is loaded the following extern "C" function is called to obtain 00199 an instance of the XrdOlbXmi object that will be used for request processing. 00200 The function is passed the command line arguments (xrd options stripped) and 00201 a pointer to the XrdOlbXmiEnv structure. If the function returns a null 00202 pointer, the olbd exits with an error. 00203 00204 After the object is obtained, XeqMode() is called to determine how each 00205 method is to operate by default. A value must be set in each provided mask 00206 for each method, as applicable. Two mask are supplied: 00207 00208 isNormal When the XMI_func bit is set in this mask, the corresponding 00209 method is executed in the normal way the olbd would 00210 have done it had the plugin not existed. Otherwise, 00211 you will have to indicate this at run-time for each call 00212 which can only be done in direct calling mode. 00213 00214 isDirect When the XMI_func bit is set in this mask, the corresponding 00215 method is called directly without thread isolation. Use 00216 this mode if the processing is immediate (e.g., you will 00217 be imediately redirecting the client). By default, the 00218 client is told to wait for a defered response and the 00219 request is queued for a thread running the Xmi plugin. 00220 Three threads are used to drive the Xmi: 00221 1) A thread to feed Prep() 00222 2) A thread to feed Select() 00223 3) A thread to feed everything else. 00224 Warning! The three thread model obviously affects how 00225 objects can be shared! 00226 */ 00227 00228 extern "C" 00229 { 00230 XrdOlbXmi *XrdOlbgetXmi(int argc, char **argv, XrdOlbXmiEnv *XmiEnv); 00231 } 00232 #endif
1.7.1