xrootd
XrdCmsClient.hh
Go to the documentation of this file.
1 #ifndef __CMS_CLIENT__
2 #define __CMS_CLIENT__
3 /******************************************************************************/
4 /* */
5 /* X r d C m s C l i e n t . h h */
6 /* */
7 /* (c) 2007 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 XrdOucEnv;
34 class XrdOucErrInfo;
35 class XrdOucLogger;
36 class XrdOucTList;
37 struct XrdSfsPrep;
38 class XrdSysLogger;
39 
40 /******************************************************************************/
41 /* R e t u r n C o n v e n t i o n s */
42 /******************************************************************************/
43 
44 /* The following return conventions are use by Forward(), Locate(), & Prepare()
45  Return Val Resp.errcode Resp.errtext
46  --------- ------------------- --------
47  SFS_DATA Length of data. Data to be returned to caller.
48  Action: Caller is provided data as successful response.
49 
50  SFS_ERROR errno Error message text.
51  Action: Caller given error response.
52 
53  SFS_REDIRECT port (0 for default) Host name
54  Action: Caller is redirected to <host>:<port>
55 
56  SFS_STARTED Expected seconds n/a
57  Action: Caller is told to wait for the "expected seconds" for a
58  callback with the result. A callback must follow.
59  See how to do callbacks below.
60 
61  > 0 Wait time (= retval) Reason for wait
62  Action: Caller told to wait retval seconds and retry request.
63 
64  < 0 Error number Error message
65  Action: Same as SFS_ERROR. You should *always* use SFS_ERROR.
66 
67  = 0 Not applicable Not applicable (see below)
68  Action: Forward() -> Return success; request forwarded.
69  Locate() -> Redirection does not apply, operation
70  should be done against local file system.
71  Prepare() -> Return success, request submitted.
72 */
73 
74 /******************************************************************************/
75 /* C a l l b a c k C o n v e n t i o n s */
76 /******************************************************************************/
77 
78 /* Most operations allow you to return SFS_STARTED to setup a callback.
79  Callback information is contained in the XrdOucErrInfo object passed to
80  Forward(), Locate() and Prepare(); the only methods that can apply callbacks.
81  Use a callback when the operation will take at least several seconds so as
82  to not occupy the calling thread for an excessive amount of time.
83 
84  The actual mechanics of a callback are rather complicated because callbacks
85  are subject to non-causaility if not correctly handled. In order to avoid
86  such issues, you should use the XrdOucCallBack object (see XrdOucCallBack.hh)
87  to test for applicability, setup, and effect a callback.
88 
89  When calling back, you return the same information you would have returned
90  had the execution path been synchronous. From that standpoint callbacks are
91  relatively easy to understand. All you are doing is defering the return of
92  information without occupying a thread while waiting to do so.
93 
94  A typical scenario, using Resp and the original ErrInfo object, would be....
95 
96  XrdOucCallBack cbObject; // Must be persistent for the callback duration
97 
98  if (XrdOucCallBack::Allowed(Resp))
99  {cbObject.Init(Resp);
100  <hand off the cbObject to a thread that will perform the work>
101  Resp.setErrCode(<seconds end-point should wait>);
102  return SFS_STARTED; // Effect callback response!
103  }
104 
105  Once the thread doing the work has a result, send it via a callback as if
106  the work was done in a synchronous fashion.
107 
108  cbObject->Reply(retValue, ErrCodeValue, ErrTextValue);
109 */
110 
111 /******************************************************************************/
112 /* C l a s s X r d C m s C l i e n t */
113 /******************************************************************************/
114 
116 {
117 public:
118 
119 //------------------------------------------------------------------------------
126 //------------------------------------------------------------------------------
127 
128 virtual void Added(const char *path, int Pend=0) { (void)path; (void)Pend; }
129 
130 //------------------------------------------------------------------------------
140 //------------------------------------------------------------------------------
141 
142 virtual int Configure(const char *cfn, char *Parms, XrdOucEnv *EnvInfo) = 0;
143 
144 //------------------------------------------------------------------------------
170 //------------------------------------------------------------------------------
171 
172 virtual int Forward(XrdOucErrInfo &Resp, const char *cmd,
173  const char *arg1=0, const char *arg2=0,
174  XrdOucEnv *Env1=0, XrdOucEnv *Env2=0)
175 {
176  (void)Resp; (void)cmd; (void)arg1; (void)arg2; (void)Env1; (void)Env2;
177  return 0;
178 }
179 
180 //------------------------------------------------------------------------------
185 //------------------------------------------------------------------------------
186 
187 virtual int isRemote() {return myPersona == XrdCmsClient::amRemote;}
188 
189 //------------------------------------------------------------------------------
216 //------------------------------------------------------------------------------
217 
218 virtual int Locate(XrdOucErrInfo &Resp, const char *path, int flags,
219  XrdOucEnv *Info=0) = 0;
220 
221 //------------------------------------------------------------------------------
227 // Return: A list of managers or null if none exist.
228 //------------------------------------------------------------------------------
229 
230 virtual
231 XrdOucTList *Managers() {return 0;}
232 
233 //------------------------------------------------------------------------------
241 //------------------------------------------------------------------------------
242 
243 virtual int Prepare(XrdOucErrInfo &Resp, XrdSfsPrep &pargs,
244  XrdOucEnv *Info=0)
245 {
246  (void)Resp; (void)pargs; (void)Info;
247  return 0;
248 }
249 
250 //------------------------------------------------------------------------------
255 //------------------------------------------------------------------------------
256 
257 virtual void Removed(const char *path) { (void)path; }
258 
259 //------------------------------------------------------------------------------
264 //------------------------------------------------------------------------------
265 
266 virtual void Resume (int Perm=1) { (void)Perm; }
267 
268 //------------------------------------------------------------------------------
273 //------------------------------------------------------------------------------
274 
275 virtual void Suspend(int Perm=1) { (void)Perm; }
276 
277 // The following set of functions can be used to control whether or not clients
278 // are dispatched to this data server based on a virtual resource. The default
279 // implementations do nothing.
280 //
281 //------------------------------------------------------------------------------
288 //------------------------------------------------------------------------------
289 
290 virtual int Resource(int n) { (void)n; return 0;}
291 
292 //------------------------------------------------------------------------------
300 //------------------------------------------------------------------------------
301 
302 virtual int Reserve (int n=1) { (void)n; return 0;}
303 
304 //------------------------------------------------------------------------------
313 //------------------------------------------------------------------------------
314 
315 virtual int Release (int n=1) { (void)n; return 0;}
316 
317 //------------------------------------------------------------------------------
326 //------------------------------------------------------------------------------
327 
328 virtual int Space(XrdOucErrInfo &Resp, const char *path,
329  XrdOucEnv *Info=0) = 0;
330 
331 //------------------------------------------------------------------------------
335 //------------------------------------------------------------------------------
336 
337  enum Persona {amLocal,
340  };
341 
342  XrdCmsClient(Persona acting) : myPersona(acting) {}
343 
344 //------------------------------------------------------------------------------
346 //------------------------------------------------------------------------------
347 
348 virtual ~XrdCmsClient() {}
349 
350 protected:
351 
353 };
354 
355 /******************************************************************************/
356 /* I n s t a n t i a t i o n M o d e F l a g s */
357 /******************************************************************************/
358 
363 namespace XrdCms
364 {
365 enum {IsProxy = 1,
366  IsRedir = 2,
367  IsTarget = 4,
368  IsMeta = 8
369  };
370 }
371 
372 /******************************************************************************/
373 /* C M S C l i e n t I n s t a n t i a t o r */
374 /******************************************************************************/
375 
376 //------------------------------------------------------------------------------
408 //------------------------------------------------------------------------------
409 
410 class XrdOss;
411 
412 typedef XrdCmsClient *(*XrdCmsClient_t)(XrdSysLogger *, int, int, XrdOss *);
413 
420 //------------------------------------------------------------------------------
433 //------------------------------------------------------------------------------
434 
435 namespace XrdCms
436 {
438  int opMode,
439  int myPort
440  );
441 }
442 
443 //------------------------------------------------------------------------------
448 //------------------------------------------------------------------------------
449 
454 #endif