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 
13 // $Id$
14 
15 class XrdBwmPolicy
16 {
17 public:
18 
19 /* General note: Each request is to be identified by an int-sized handle.
20  The value of the handle is unique with respect to all of the
21  requests that are active and queued. Once a request leaves
22  the system (i.e., cancelled or released) the handle may be
23  re-used. Handle signs are immaterial. That is the property
24  "n == abs(-n) == <same request>" always must hold. Note that
25  Schedule() uses negative handles to merely indicate queuing.
26 */
27 
28 /* Dispatch() returns the handle of the next request that may become active
29  because the resources are now available or that must be terminated
30  because resources are not available. The returned value must have the
31  the following property: "Dispatch() == abs(Schedule()) == <same request>".
32  Hence, the handle returned by Dispatch() must be one previously returned by
33  Schedule() that was negative to indicate that the request was queued. The
34  sign of the returned handle indicates success or failure:
35 
36  returns < 0: The associated previously scheduled request cannot obtain
37  the resource. RespBuff, of size RespSize, should contain
38  null terminated text describing the failure. Done() will not
39  called for the returned handle.
40  returns >= 0: The associated previously scheduled request can now be
41  dispatched as resources are available. RespBuff, of size
42  RespSize, should contain any visa information, as an
43  ASCII null terminated string to be sent to client. If none,
44  it should contain a null string (i.e., zero byte). Done()
45  will be called for the returned handle when the resource is no
46  longer needed.
47 
48  Dispatch() blocks until a request is ready or has failed.
49 */
50 
51 virtual int Dispatch(char *RespBuff, int RespSize) = 0;
52 
53 /* Done() indicates that the resources with a previous request associated with
54  the handle, as returned by Dispatch() and Schedule(). When Done() is called
55  with a handle referring to a queued request, the request should be cancelled
56  and removed from the queue. If the handle refers to an active request (i.e.,
57  a non-negative one that was returned by Dispatch()), the resources associated
58  with the dispatched request are no longer needed and are to be made available
59  to another request. The value returned by Done() indicates what happened:
60 
61  returns < 0: The queued request was cancelled.
62  returns = 0: No request matching the handle was found.
63  returns > 0: The resources associated with the dispatched request returned.
64 
65  The handle itself may be a positive or negative, as returned by Dispatch()
66  and Schedule(). Note that "n == abs(-n) == <same request>", so the sign
67  of the handle should be immaterial to Done(). Negative handles returned by
68  Dispatch() indicate failure and thus Done() will not be called for such
69  handles. Handles returned by Schedule() may be postive or negative.
70 */
71 
72 virtual int Done(int rHandle) = 0;
73 
74 /* Schedule() is invoked when the caller wishes to obtain resources controlled
75  by the policy. The caller passes a pointer to a response buffer, RespBuff,
76  of size contained in RespSize, to hold hold any response. Additionally. a
77  reference to the SchedParms struct that contains information about the
78  nature of the request. Schedule() may choose to immediately allow the
79  resourse to be used, fail the request, or to defer the request.
80  This is indicated by the returned int, as follows:
81 
82  returns < 0: The request has been queued. The returned value is the handle
83  for the request and is to be used as the argument to Done() to
84  cancel the queued request.
85 
86  returns = 0: The request failed. The RespBuff should contain any error text
87  or a null byte if no text is present.
88 
89  returns > 0: The request succeeded and the resource can be used. The returned
90  value is the handle for the request and is to be used as the
91  argument to Done() to release the associated request resource.
92 
93  RespBuff should contain any visa information, as an ASCII null
94  terminated string to be sent to client. If none, it
95  must contain a null string (i.e., zero byte).
96 */
97 enum Flow {Incomming = 0, Outgoing};
98 
99 struct SchedParms
100 {
101 const char *Tident; // In: -> Client's trace identity
102  char *Lfn; // In: -> Logical File Name
103  char *LclNode; // In: -> Local node involved in the request
104  char *RmtNode; // In: -> Remote node involved in the request
105  Flow Direction; // In: -> Data flow relative to Lclpoint (see enum)
106 };
107 
108 virtual int Schedule(char *RespBuff, int RespSize, SchedParms &Parms) = 0;
109 
110 /* Status() returns the number of requests as three items via parameters:
111  numqIn - Number of incomming data requests queued
112  numqOut - Number of outgoing data requests queued
113  numXeq - Number of requests that are active (in or out).
114 */
115 
116 virtual void Status(int &numqIn, int &numqOut, int &numXeq) = 0;
117 
118  XrdBwmPolicy() {}
119 
120 virtual ~XrdBwmPolicy() {}
121 };
122 
123 /******************************************************************************/
124 /* X r d B w m P o l i c y O b j e c t */
125 /******************************************************************************/
126 
127 class XrdSysLogger;
128 
129 /* XrdBwmPolicyObject() is called to obtain an instance of the policy object
130  that will be used for all subsequent policy scheduling requests. If it
131  returns a null pointer; initialization fails and the program exits.
132  The args are:
133 
134  lp -> XrdSysLogger to be tied to an XrdSysError object for messages
135  cfn -> The name of the configuration file
136  parm -> Parameters specified on the policy lib directive. If none it's zero.
137 */
138 
139 extern "C" XrdBwmPolicy *XrdBwmPolicyObject(XrdSysLogger *lp,
140  const char *cfn,
141  const char *parm);
142 #endif
Generated by   doxygen 1.8.1.2