00001 #ifndef __BWM_POLICY__ 00002 #define __BWM_POLICY__ 00003 /******************************************************************************/ 00004 /* */ 00005 /* X r d B w m P o l i c y . h h */ 00006 /* */ 00007 /* (c) 2008 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 /* This file is part of the XRootD software suite. */ 00013 /* */ 00014 /* XRootD is free software: you can redistribute it and/or modify it under */ 00015 /* the terms of the GNU Lesser General Public License as published by the */ 00016 /* Free Software Foundation, either version 3 of the License, or (at your */ 00017 /* option) any later version. */ 00018 /* */ 00019 /* XRootD is distributed in the hope that it will be useful, but WITHOUT */ 00020 /* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or */ 00021 /* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public */ 00022 /* License for more details. */ 00023 /* */ 00024 /* You should have received a copy of the GNU Lesser General Public License */ 00025 /* along with XRootD in a file called COPYING.LESSER (LGPL license) and file */ 00026 /* COPYING (GPL license). If not, see <http://www.gnu.org/licenses/>. */ 00027 /* */ 00028 /* The copyright holder's institutional names and contributor's names may not */ 00029 /* be used to endorse or promote products derived from this software without */ 00030 /* specific prior written permission of the institution or contributor. */ 00031 /******************************************************************************/ 00032 00033 class XrdBwmPolicy 00034 { 00035 public: 00036 00037 /* General note: Each request is to be identified by an int-sized handle. 00038 The value of the handle is unique with respect to all of the 00039 requests that are active and queued. Once a request leaves 00040 the system (i.e., cancelled or released) the handle may be 00041 re-used. Handle signs are immaterial. That is the property 00042 "n == abs(-n) == <same request>" always must hold. Note that 00043 Schedule() uses negative handles to merely indicate queuing. 00044 */ 00045 00046 /* Dispatch() returns the handle of the next request that may become active 00047 because the resources are now available or that must be terminated 00048 because resources are not available. The returned value must have the 00049 the following property: "Dispatch() == abs(Schedule()) == <same request>". 00050 Hence, the handle returned by Dispatch() must be one previously returned by 00051 Schedule() that was negative to indicate that the request was queued. The 00052 sign of the returned handle indicates success or failure: 00053 00054 returns < 0: The associated previously scheduled request cannot obtain 00055 the resource. RespBuff, of size RespSize, should contain 00056 null terminated text describing the failure. Done() will not 00057 called for the returned handle. 00058 returns >= 0: The associated previously scheduled request can now be 00059 dispatched as resources are available. RespBuff, of size 00060 RespSize, should contain any visa information, as an 00061 ASCII null terminated string to be sent to client. If none, 00062 it should contain a null string (i.e., zero byte). Done() 00063 will be called for the returned handle when the resource is no 00064 longer needed. 00065 00066 Dispatch() blocks until a request is ready or has failed. 00067 */ 00068 00069 virtual int Dispatch(char *RespBuff, int RespSize) = 0; 00070 00071 /* Done() indicates that the resources with a previous request associated with 00072 the handle, as returned by Dispatch() and Schedule(). When Done() is called 00073 with a handle referring to a queued request, the request should be cancelled 00074 and removed from the queue. If the handle refers to an active request (i.e., 00075 a non-negative one that was returned by Dispatch()), the resources associated 00076 with the dispatched request are no longer needed and are to be made available 00077 to another request. The value returned by Done() indicates what happened: 00078 00079 returns < 0: The queued request was cancelled. 00080 returns = 0: No request matching the handle was found. 00081 returns > 0: The resources associated with the dispatched request returned. 00082 00083 The handle itself may be a positive or negative, as returned by Dispatch() 00084 and Schedule(). Note that "n == abs(-n) == <same request>", so the sign 00085 of the handle should be immaterial to Done(). Negative handles returned by 00086 Dispatch() indicate failure and thus Done() will not be called for such 00087 handles. Handles returned by Schedule() may be postive or negative. 00088 */ 00089 00090 virtual int Done(int rHandle) = 0; 00091 00092 /* Schedule() is invoked when the caller wishes to obtain resources controlled 00093 by the policy. The caller passes a pointer to a response buffer, RespBuff, 00094 of size contained in RespSize, to hold hold any response. Additionally. a 00095 reference to the SchedParms struct that contains information about the 00096 nature of the request. Schedule() may choose to immediately allow the 00097 resourse to be used, fail the request, or to defer the request. 00098 This is indicated by the returned int, as follows: 00099 00100 returns < 0: The request has been queued. The returned value is the handle 00101 for the request and is to be used as the argument to Done() to 00102 cancel the queued request. 00103 00104 returns = 0: The request failed. The RespBuff should contain any error text 00105 or a null byte if no text is present. 00106 00107 returns > 0: The request succeeded and the resource can be used. The returned 00108 value is the handle for the request and is to be used as the 00109 argument to Done() to release the associated request resource. 00110 00111 RespBuff should contain any visa information, as an ASCII null 00112 terminated string to be sent to client. If none, it 00113 must contain a null string (i.e., zero byte). 00114 */ 00115 enum Flow {Incomming = 0, Outgoing}; 00116 00117 struct SchedParms 00118 { 00119 const char *Tident; // In: -> Client's trace identity 00120 char *Lfn; // In: -> Logical File Name 00121 char *LclNode; // In: -> Local node involved in the request 00122 char *RmtNode; // In: -> Remote node involved in the request 00123 Flow Direction; // In: -> Data flow relative to Lclpoint (see enum) 00124 }; 00125 00126 virtual int Schedule(char *RespBuff, int RespSize, SchedParms &Parms) = 0; 00127 00128 /* Status() returns the number of requests as three items via parameters: 00129 numqIn - Number of incomming data requests queued 00130 numqOut - Number of outgoing data requests queued 00131 numXeq - Number of requests that are active (in or out). 00132 */ 00133 00134 virtual void Status(int &numqIn, int &numqOut, int &numXeq) = 0; 00135 00136 XrdBwmPolicy() {} 00137 00138 virtual ~XrdBwmPolicy() {} 00139 }; 00140 00141 /******************************************************************************/ 00142 /* X r d B w m P o l i c y O b j e c t */ 00143 /******************************************************************************/ 00144 00145 class XrdSysLogger; 00146 00147 /* XrdBwmPolicyObject() is called to obtain an instance of the policy object 00148 that will be used for all subsequent policy scheduling requests. If it 00149 returns a null pointer; initialization fails and the program exits. 00150 The args are: 00151 00152 lp -> XrdSysLogger to be tied to an XrdSysError object for messages 00153 cfn -> The name of the configuration file 00154 parm -> Parameters specified on the policy lib directive. If none it's zero. 00155 */ 00156 00157 extern "C" XrdBwmPolicy *XrdBwmPolicyObject(XrdSysLogger *lp, 00158 const char *cfn, 00159 const char *parm); 00160 #endif