XrdOucCallBack.hh

Go to the documentation of this file.
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)
00104 { (void)Result; (void)eInfo; (void)Path; cbSync.Post();}
00105 int   Same(unsigned long long arg1, unsigned long long arg2)
00106 { (void)arg1; (void)arg2; return 0;}
00107 
00108 XrdSysSemaphore     cbSync;
00109 unsigned long long  cbArg;
00110 XrdOucEICB         *cbObj;
00111 char                UserID[64];
00112 };
00113 #endif

Generated on 12 Dec 2014 for xrootd by  doxygen 1.4.7