xrootd
XrdBwmPolicy.hh
Go to the documentation of this file.
1 #ifndef __BWM_POLICY__
2 #define __BWM_POLICY__
3 /******************************************************************************/
4 /* */
5 /* X r d B w m P o l i c y . h h */
6 /* */
7 /* (c) 2008 by the Board of Trustees of the Leland Stanford, Jr., University */
8 /* All Rights Reserved */
9 /* Produced by Andrew Hanushevsky for Stanford University under contract */
10 /* DE-AC02-76-SFO0515 with the Department of Energy */
11 /* */
12 /* This file is part of the XRootD software suite. */
13 /* */
14 /* XRootD is free software: you can redistribute it and/or modify it under */
15 /* the terms of the GNU Lesser General Public License as published by the */
16 /* Free Software Foundation, either version 3 of the License, or (at your */
17 /* option) any later version. */
18 /* */
19 /* XRootD is distributed in the hope that it will be useful, but WITHOUT */
20 /* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or */
21 /* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public */
22 /* License for more details. */
23 /* */
24 /* You should have received a copy of the GNU Lesser General Public License */
25 /* along with XRootD in a file called COPYING.LESSER (LGPL license) and file */
26 /* COPYING (GPL license). If not, see <http://www.gnu.org/licenses/>. */
27 /* */
28 /* The copyright holder's institutional names and contributor's names may not */
29 /* be used to endorse or promote products derived from this software without */
30 /* specific prior written permission of the institution or contributor. */
31 /******************************************************************************/
32 
33 class XrdBwmPolicy
34 {
35 public:
36 
37 /* General note: Each request is to be identified by an int-sized handle.
38  The value of the handle is unique with respect to all of the
39  requests that are active and queued. Once a request leaves
40  the system (i.e., cancelled or released) the handle may be
41  re-used. Handle signs are immaterial. That is the property
42  "n == abs(-n) == <same request>" always must hold. Note that
43  Schedule() uses negative handles to merely indicate queuing.
44 */
45 
46 /* Dispatch() returns the handle of the next request that may become active
47  because the resources are now available or that must be terminated
48  because resources are not available. The returned value must have the
49  the following property: "Dispatch() == abs(Schedule()) == <same request>".
50  Hence, the handle returned by Dispatch() must be one previously returned by
51  Schedule() that was negative to indicate that the request was queued. The
52  sign of the returned handle indicates success or failure:
53 
54  returns < 0: The associated previously scheduled request cannot obtain
55  the resource. RespBuff, of size RespSize, should contain
56  null terminated text describing the failure. Done() will not
57  called for the returned handle.
58  returns >= 0: The associated previously scheduled request can now be
59  dispatched as resources are available. RespBuff, of size
60  RespSize, should contain any visa information, as an
61  ASCII null terminated string to be sent to client. If none,
62  it should contain a null string (i.e., zero byte). Done()
63  will be called for the returned handle when the resource is no
64  longer needed.
65 
66  Dispatch() blocks until a request is ready or has failed.
67 */
68 
69 virtual int Dispatch(char *RespBuff, int RespSize) = 0;
70 
71 /* Done() indicates that the resources with a previous request associated with
72  the handle, as returned by Dispatch() and Schedule(). When Done() is called
73  with a handle referring to a queued request, the request should be cancelled
74  and removed from the queue. If the handle refers to an active request (i.e.,
75  a non-negative one that was returned by Dispatch()), the resources associated
76  with the dispatched request are no longer needed and are to be made available
77  to another request. The value returned by Done() indicates what happened:
78 
79  returns < 0: The queued request was cancelled.
80  returns = 0: No request matching the handle was found.
81  returns > 0: The resources associated with the dispatched request returned.
82 
83  The handle itself may be a positive or negative, as returned by Dispatch()
84  and Schedule(). Note that "n == abs(-n) == <same request>", so the sign
85  of the handle should be immaterial to Done(). Negative handles returned by
86  Dispatch() indicate failure and thus Done() will not be called for such
87  handles. Handles returned by Schedule() may be postive or negative.
88 */
89 
90 virtual int Done(int rHandle) = 0;
91 
92 /* Schedule() is invoked when the caller wishes to obtain resources controlled
93  by the policy. The caller passes a pointer to a response buffer, RespBuff,
94  of size contained in RespSize, to hold hold any response. Additionally. a
95  reference to the SchedParms struct that contains information about the
96  nature of the request. Schedule() may choose to immediately allow the
97  resourse to be used, fail the request, or to defer the request.
98  This is indicated by the returned int, as follows:
99 
100  returns < 0: The request has been queued. The returned value is the handle
101  for the request and is to be used as the argument to Done() to
102  cancel the queued request.
103 
104  returns = 0: The request failed. The RespBuff should contain any error text
105  or a null byte if no text is present.
106 
107  returns > 0: The request succeeded and the resource can be used. The returned
108  value is the handle for the request and is to be used as the
109  argument to Done() to release the associated request resource.
110 
111  RespBuff should contain any visa information, as an ASCII null
112  terminated string to be sent to client. If none, it
113  must contain a null string (i.e., zero byte).
114 */
115 enum Flow {Incomming = 0, Outgoing};
116 
117 struct SchedParms
118 {
119 const char *Tident; // In: -> Client's trace identity
120  char *Lfn; // In: -> Logical File Name
121  char *LclNode; // In: -> Local node involved in the request
122  char *RmtNode; // In: -> Remote node involved in the request
123  Flow Direction; // In: -> Data flow relative to Lclpoint (see enum)
124 };
125 
126 virtual int Schedule(char *RespBuff, int RespSize, SchedParms &Parms) = 0;
127 
128 /* Status() returns the number of requests as three items via parameters:
129  numqIn - Number of incomming data requests queued
130  numqOut - Number of outgoing data requests queued
131  numXeq - Number of requests that are active (in or out).
132 */
133 
134 virtual void Status(int &numqIn, int &numqOut, int &numXeq) = 0;
135 
136  XrdBwmPolicy() {}
137 
138 virtual ~XrdBwmPolicy() {}
139 };
140 
141 /******************************************************************************/
142 /* X r d B w m P o l i c y O b j e c t */
143 /******************************************************************************/
144 
145 class XrdSysLogger;
146 
147 /* XrdBwmPolicyObject() is called to obtain an instance of the policy object
148  that will be used for all subsequent policy scheduling requests. If it
149  returns a null pointer; initialization fails and the program exits.
150  The args are:
151 
152  lp -> XrdSysLogger to be tied to an XrdSysError object for messages
153  cfn -> The name of the configuration file
154  parm -> Parameters specified on the policy lib directive. If none it's zero.
155 */
156 
157 extern "C" XrdBwmPolicy *XrdBwmPolicyObject(XrdSysLogger *lp,
158  const char *cfn,
159  const char *parm);
160 #endif
Generated by   doxygen 1.8.3.1