dcpphandler.h

/*
 * Name: filter.m4
 *
 * Description:
 *     DOXYGEN Input file filter for DRAMA source files.
 *
 *     This file must be complatible with both Solaris and GNU m4.  All
 *     unused macros are deleted and this comment must end up as a C/C++
 *     compatible comment which is not picked up by DOXYGEN.
 * 
 * Synopsis:
 *    DCF(func)  => Produces a link to a DRAMA C source file func.html 
 *                   in ../routines.
 *     DDL(link,text) => Produce a link to ../link.html, specified link text.
 *
 * Language: m4 macro. 
 *
 * Author: Tony Farrell, AAO.
 *
 * "@(#) $Id$"
 *
 * History:
 *     10-Nov-2004 - TJF - Original Version.
 */
 
 
 
#ifndef dcpphandler_h
#define dcpphandler_h
/*                            d c p p h a n d l e r
  
 * Module name:
      dcpphandler.h
  
 * Function:
        A class that completly hides the details of action reschedule.
  
 * Description:
        When a DcppHandler object is installed for the current action,
        it calls DitsPutObeyHandler supplying its own routine to handle
        future reschedules of the action.  The idea is that the various
        handlers will be invoked when events occur.  By returning
        DcppReschedule, they indicate that reschedule should occur,
        Otherwise they should return DcppFinished.        
  
        This file now uses DOXYGEN comments to generate the C++ web pages.
        m4 macros of the form @htmlonly <a href="../routines/function.html">function()</a>@endhtmlonly are used in the comments
        to refer to DRAMA C function documention (see DramaHtml/Makefile,
        DramaHtml/doxygen.config and DramaHtml/filter.m4 for detials)
 
 * Language:
      C++
  
 * Support: Tony Farrell, AAO
  
 * Copyright (c) Anglo-Australian Telescope Board, 1995.
   Not to be used for commercial purposes without AATB permission.
  
 *    @(#) $Id$
  
 * History:
      12-Oct-1995 - TJF - Original version.  Taken from dcpp.h
      25-Sep-1996 - TJF - Extensively modified to support multiple
                                threads.
      09-Dec-1997 - TJF - Declare class with DPUBLICCLASS to allow
                          export from WIN32 DLL.
      02-Feb-1998 - TJF - Declare ReschedHandler static function using
                          DSTATICMEM macro to support WIN32 DLL correctly.
      23-Nov-1998 - TJF - SetTimeout now does DitsPutDelay() to ensure
                          we can install and then to SetTimeout().  But
                          unsetting timeout does not work.
      17-Nov-1999 - TJF - Add NewThread method.  The increment operators
                          are now obsolete and will be removed.
      19-Nov-1999 - TJF - Add ability to set a timeout handler.
      12-Sep-2003 - TJF - Add new ThreadCount() function to help in debugging.
      17-Sep-2003 - TJF - Use Dits___Log for logging and log handler being
                          installed.
      26-Sep-2003 - TJF - GCC 3.x complains if printf style arguments for
                          the %p formater are not cast to void *.  Fixed.
      19-Jan-2004 - TJF - The external interface is now virtual and
                          all significant virtual functions are now moved
                          to dcpphandler.C.
      19-Aug-2004 - MVV - Added a member data that is a pointer to 
                          DcppCallbackBase type.
      18-Oct-2004 - TJF - Include DitsFix.h - it is needed by IsUface() to get
                            DitsGetContext().
      01-Dec-2004 - TJF - Improve Wait and WaitAll headers.
  
 */
#include "dcpp.h"
#include "DitsFix.h"
#include "dcppcallbackbase.h"
DPUBLICCLASS DcppHandler {
    private:
        DcppHandlerRoutine finishedHandler;     /* User supplied routine to invoke when messages complete*/
        DcppHandlerRoutine errorHandler;        /* User supplied routine to inovked on errors   */
        DcppHandlerRoutine timeoutHandler;      /* User supplied routine to inovked on timeout  */
        DcppVoidPnt oldActData;                 /* actData is saved here                        */
        DcppVoidPnt clientData;                 /* Client data item for handlers                */
        DitsDeltaTimeType delay;                /* Timeout between reschedules                  */
        bool timeoutEnabled;                    /* Is the timeout enabled                       */
        StatusType errorStat;                   /* Status of first error in current sequence    */
        int threadCount;                        /* Number of outstanding threads                */
        int initThreads;                        /* When reinitialising threads, use this value  */
        int errorCount;                         /* Number of threads which completed in error   */
        bool errorMode;                 /* If true errorHandler is invoked for each     */
                                                /* thread on which an error occurs instead of   */
                                                /* when all threads have completed              */
        bool *destroyedPtr;   /* IF non-null, then contains a pointer to
                                 a bool which should be set true by the
                                 destructor - allowing HandleReschedule()
                                 to work out if the handler was destroyed
                                 whilst it was run
                              */
 
        DcppCallbackBase* callbackObj;
 
        void ErrorHandler(StatusType * status); 
        void TimeoutHandler(StatusType * status); 
        void FinishedHandler(StatusType * status);
 
        bool IsUface() const
        { 
            return ((DitsGetContext() == DITS_CTX_UFACE) ? true : false);
        }
 
/*
 *      Prevent Assignment and copying of this type by redefining the
 *      assignment and copy operators to be private.
 *      This ensures we can't get multiple threads controlling the one
 *      task unless done intentionally by the caller.
 *
 *      Disallow the default constructor.
 */
        DcppHandler& operator=(const DcppHandler&);
        DcppHandler(const DcppHandler&);
 
 
     public:
        DcppHandler(const DcppHandlerRoutine FinishedHandler = 0,
                    const DcppHandlerRoutine ErrorHandler = 0,
                    const DcppVoidPnt ClientData = 0, 
                    const float Timeout = -1);
 
        DcppHandler(DcppCallbackBase* CallbackObj,
                    const float Timeout = -1);
 
 
        virtual void Install(StatusType * status, int threads = 1);
 
        virtual void DeInstall(StatusType * const status);
 
        virtual void SetFinished(const DcppHandlerRoutine FinishedHandler) {
                finishedHandler = FinishedHandler;
        };
     
        void Wait(DitsTransIdType transId, StatusType* status, double timeout = 0);
 
        void WaitAll(StatusType* status, double timeout = 0);
 
        virtual void SetError   (const DcppHandlerRoutine ErrorHandler) {
                errorHandler = ErrorHandler;
        };
        virtual void SetData    (const DcppVoidPnt ClientData) {
                clientData = ClientData;
        };
        virtual void SetTimeout(const float Timeout);
 
        virtual void SetTimeout   (const DcppHandlerRoutine TimeoutHandler,
                           const float Timeout) {
                SetTimeout(Timeout);
                timeoutHandler = TimeoutHandler;
        };
        virtual void SetMultiCallErrorMode(int enable = true) {
            errorMode = enable;
        }
        virtual StatusType ErrorStatus() const { return errorStat; }
 
        virtual DcppVoidPnt GetData() const { return clientData; }
        
        virtual int ThreadCount() const { return threadCount; }
        void operator++() {     /* Preincrement operator */
            if (TheTask(debug) & DITS_LOG_LIBS)
                Dits___Log("DcppHd::++[pre]",
                           "Thread count incremented for %p from %d to %d",
                           (void *)this, threadCount, threadCount+1);
            ++threadCount;
        }
        void operator++(int) { /* Post increment operator */
            if (TheTask(debug) & DITS_LOG_LIBS)
                Dits___Log("DcppHd::++[post]",
                           "Thread count incremented for %p from %d to %d",
                           (void *)this, threadCount, threadCount+1);
            ++threadCount;
        }
        virtual void NewThread() {
            if (TheTask(debug) & DITS_LOG_LIBS)
                Dits___Log("DcppHd::NewThread",
                           "Thread count incremented for %p from %d to %d",
                           (void *)this, threadCount, threadCount+1);
            
            ++threadCount;
        }
 
        virtual ~DcppHandler();
 
        void HandleReschedule(StatusType * status);
 
        void SetupTimeout(const float Timeout);
 
};
 
 
#endif