00001 #ifndef __XRDOUCCALLBACK__HH_ 00002 #define __XRDOUCCALLBACK__HH_ 00003 /******************************************************************************/ 00004 /* */ 00005 /* X r d O u c C a l l B a c k . h h */ 00006 /* */ 00007 /* (c) 2011 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 #include "XrdOuc/XrdOucErrInfo.hh" 00034 #include "XrdSys/XrdSysPthread.hh" 00035 00036 /* The XrdOucCallBack object encapsulates the vagaries of handling callbacks 00037 in the xrootd framework; where callbacks are allowed. Once a callback is 00038 successfully established using Init() this object should not be deleted 00039 until Reply() of Cancel() is called. The destructor automatically calls 00040 Cancel() is a callback is outstanding. The object may be reused after 00041 Cancel() or Reply is called. See warnings on Init() and Cancel(). 00042 00043 This object is not MT-safe and must be used in a serial fashion. 00044 */ 00045 00046 class XrdOucCallBack : public XrdOucEICB 00047 { 00048 public: 00049 00050 /* Allowed() tell you whether or not am XrdOucErrInfo object has been setup to 00051 allow callbacks. You should test this before assuming you can use 00052 the object to effect a callback. 00053 00054 Returns: True - if a callback is allowed. 00055 False - otherwise. 00056 */ 00057 static int Allowed(XrdOucErrInfo *eInfo) {return eInfo->getErrCB() != 0;} 00058 00059 /* Cancel() cancels the callback. If no callback is oustanding, it does 00060 nothing. Otherwise, the associated endpoint is told to retry 00061 whatever operation caused the callback to be setup. Warning, 00062 calling Cancel() or deleting this object after calling Init() 00063 but not effecting a callback response will cause the calling 00064 thread to hang! 00065 */ 00066 void Cancel(); 00067 00068 /* Init() sets up a call back using the provided XrdOucErrInfo object. 00069 You must successfully call Init() before calling Reply()! 00070 Warning, once you cann Init() you *must* effect a callback 00071 response; otherwise, it is likely a subsequent thread using 00072 this object will hang! 00073 00074 Returns: True - if a callback was set up. 00075 False - otherwise (i.e., object does not allow callbacks). 00076 */ 00077 int Init(XrdOucErrInfo *eInfo); 00078 00079 /* Reply() sends the specified results to the endpoint associated with the 00080 callback esablished by Init(). The parameters are: 00081 retVal - The value you would have synchrnously returned. 00082 eValue - The numeric value that would have been returned in the 00083 original XrdOucErrInfo object. 00084 eText - The character string that would have been returned in the 00085 original XrdOucErrInfo object. 00086 Path - Optional path related to the reply. It is passed to the 00087 callback effector and is used for tracing & monitoring. 00088 00089 Returns: True - if a callback was initiated. 00090 False - callback failed; likely Init() was not successfully called. 00091 */ 00092 int Reply(int retVal, int eValue, const char *eText, 00093 const char *Path=0); 00094 00095 XrdOucCallBack() : Next(0), cbSync(0), cbArg(0), cbObj(0) {} 00096 ~XrdOucCallBack() {if (cbObj) Cancel();} 00097 00098 // The following is a handy pointer to allow for linking these objects together 00099 // 00100 XrdOucCallBack *Next; 00101 00102 private: 00103 void Done(int &Result,XrdOucErrInfo *eInfo,const char *Path=0) {cbSync.Post();} 00104 int Same(unsigned long long arg1, unsigned long long arg2) {return 0;} 00105 00106 XrdSysSemaphore cbSync; 00107 unsigned long long cbArg; 00108 XrdOucEICB *cbObj; 00109 char UserID[64]; 00110 }; 00111 #endif