xrootd
XrdOucCallBack.hh
Go to the documentation of this file.
1 #ifndef __XRDOUCCALLBACK__HH_
2 #define __XRDOUCCALLBACK__HH_
3 /******************************************************************************/
4 /* */
5 /* X r d O u c C a l l B a c k . h h */
6 /* */
7 /* (c) 2011 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 #include "XrdOuc/XrdOucErrInfo.hh"
14 #include "XrdSys/XrdSysPthread.hh"
15 
16 /* The XrdOucCallBack object encapsulates the vagaries of handling callbacks
17  in the xrootd framework; where callbacks are allowed. Once a callback is
18  successfully established using Init() this object should not be deleted
19  until Reply() of Cancel() is called. The destructor automatically calls
20  Cancel() is a callback is outstanding. The object may be reused after
21  Cancel() or Reply is called. See warnings on Init() and Cancel().
22 
23  This object is not MT-safe and must be used in a serial fashion.
24 */
25 
26 class XrdOucCallBack : public XrdOucEICB
27 {
28 public:
29 
30 /* Allowed() tell you whether or not am XrdOucErrInfo object has been setup to
31  allow callbacks. You should test this before assuming you can use
32  the object to effect a callback.
33 
34  Returns: True - if a callback is allowed.
35  False - otherwise.
36 */
37 static int Allowed(XrdOucErrInfo *eInfo) {return eInfo->getErrCB() != 0;}
38 
39 /* Cancel() cancels the callback. If no callback is oustanding, it does
40  nothing. Otherwise, the associated endpoint is told to retry
41  whatever operation caused the callback to be setup. Warning,
42  calling Cancel() or deleting this object after calling Init()
43  but not effecting a callback response will cause the calling
44  thread to hang!
45 */
46  void Cancel();
47 
48 /* Init() sets up a call back using the provided XrdOucErrInfo object.
49  You must successfully call Init() before calling Reply()!
50  Warning, once you cann Init() you *must* effect a callback
51  response; otherwise, it is likely a subsequent thread using
52  this object will hang!
53 
54  Returns: True - if a callback was set up.
55  False - otherwise (i.e., object does not allow callbacks).
56 */
57  int Init(XrdOucErrInfo *eInfo);
58 
59 /* Reply() sends the specified results to the endpoint associated with the
60  callback esablished by Init(). The parameters are:
61  retVal - The value you would have synchrnously returned.
62  eValue - The numeric value that would have been returned in the
63  original XrdOucErrInfo object.
64  eText - The character string that would have been returned in the
65  original XrdOucErrInfo object.
66  Path - Optional path related to the reply. It is passed to the
67  callback effector and is used for tracing & monitoring.
68 
69  Returns: True - if a callback was initiated.
70  False - callback failed; likely Init() was not successfully called.
71 */
72  int Reply(int retVal, int eValue, const char *eText,
73  const char *Path=0);
74 
75  XrdOucCallBack() : Next(0), cbSync(0), cbArg(0), cbObj(0) {}
76  ~XrdOucCallBack() {if (cbObj) Cancel();}
77 
78 // The following is a handy pointer to allow for linking these objects together
79 //
80 XrdOucCallBack *Next;
81 
82 private:
83 void Done(int &Result, XrdOucErrInfo *eInfo) {cbSync.Post();}
84 int Same(unsigned long long arg1, unsigned long long arg2) {return 0;}
85 
86 XrdSysSemaphore cbSync;
87 unsigned long long cbArg;
88 XrdOucEICB *cbObj;
89 char UserID[64];
90 };
91 #endif
Generated by   doxygen 1.8.1.2