dcpp.h

Go to the documentation of this file.

/*
 * 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 DCPPINC
#define DCPPINC
/*
 *
 *  Copyright (c) Anglo-Australian Telescope Board, 1995.
 *  Not to be used for commercial purposes without AATB permission.
 *
 *     @(#) $Id$
 *
 */
 
/*
 *
 * 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 documentation (see DramaHtml/Makefile,
 * DramaHtml/doxygen.config and DramaHtml/filter.m4 for detials)
 */
 
#include "DitsTypes.h"
#include "DitsInteraction.h"
#include "DitsBulk.h"
#include "sds.h"
#include "arg.h"
#include "dcpp_err.h"
 
const unsigned DcppNodeNameLen = 100;   
const unsigned DcppArgumentLen = 200;   
typedef  void * DcppVoidPnt;    
typedef  DcppVoidPnt * DcppVoidPntPnt;
/*
 * There are a few places where we set up SDS structures with variable
 * lists of arguments, with the name format Argument%d.  We support
 * only 9999 such arguments - which requires a lenght of 13 characters
 * for the Argument%d string - 8 for Argument, 4 for the number, 1 for null.
 */
const unsigned DcppMaxArgs = 9999;
const unsigned DcppArgNameLen = 13; 
 
typedef enum { DcppReschedule,
               DcppNotHandled,
               DcppFinished   
                } DcppHandlerRet;
 
typedef DcppHandlerRet (*DcppHandlerRoutine)
                        (DcppVoidPnt ClientData, StatusType *status);
 
typedef void (*DcppBulkTransRoutine)
                        (unsigned long Transferred,
                         unsigned long Total,
                         DcppVoidPnt ClientData, StatusType *status);
 
DPUBLIC DcppHandlerRet DcppDispatch(StatusType *const status);
 
/* Call to DcppDispatch which ignores the return, 
 * since in modern C++ casting DcppDispatch to DitsActionRoutineType
 * gets warnings
 */
DPUBLIC void Dcpp___UfaceDispatch(StatusType *const status);
 
inline void DcppUfaceCtxEnable(StatusType * const status) {
    DitsUfaceCtxEnable(DitsActionRoutineType(Dcpp___UfaceDispatch),0,status);
}
 
 
/*
 *  Routines which provide wrappers around DitsSpawnKickArg and
 *  DitsSpawnKickArgUpdate.
 */
DPUBLIC void DcppSpawnKickArg(
    DitsTransIdType transid,
    SdsId * id,
    StatusType *status);
 
DPUBLIC void DcppSpawnKickArgUpdate(
    DitsTransIdType transid,
    const SdsId * id,
    StatusType *status);
 
 
DPUBLICCLASS DcppTask;  /*Forward declaration */
 
DPUBLIC DVOID DcppForgetAll(
    DVOIDP client_data,
    int taskExit,
    StatusType exitStatus,
    StatusType * const status);
 
DPUBLIC void DcppVarArgsToSds(
    int count, 
    Arg& ArgId,
    StatusType * status, 
    va_list args);
 
/*
 * * *  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 */
DPUBLICCLASS DcppBuffers {
    private:
        DitsPathInfoType bufInfo;
    public:
        DcppBuffers( long int MessageBytes = 800,
                     long int MaxMessages = 2,
                     long int ReplyBytes = 800,
                     long int MaxReplies = 2) {
                bufInfo.MessageBytes = MessageBytes;
                bufInfo.MaxMessages  = MaxMessages;
                bufInfo.ReplyBytes   = ReplyBytes;
                bufInfo.MaxReplies   = MaxReplies; 
        };
        DcppBuffers ( const DitsPathInfoType & i) : bufInfo(i) {};
        operator const DitsPathInfoType * () const { 
                return &bufInfo; }
        long int MessageBytes() const { return bufInfo.MessageBytes; };
        long int MaxMessages()  const { return bufInfo.MaxMessages;  };
        long int ReplyBytes()   const { return bufInfo.ReplyBytes;   };
        long int MaxReplies()   const { return bufInfo.MaxReplies;   }; 
};
 
 
/*
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *  DcppTransaction - keeps track of transactions.  A transaction structure
 *  is normally stored using DitsPutTransData and retrieved using 
 *  DitsGetTransData.  A check value is put in the data structure and is 
 *  used to ensure the item fetched by DitsGetTransData is valid.
 *      
 */
const long int DcppCheckData = 0x0e0e0e0e; 
DPUBLICCLASS DcppTransaction {
    private:
        long int checkvalue;               /* Check value, must be first */
        DcppHandlerRoutine successHandler;
                                /* Called on completion without error */
        DcppHandlerRoutine errorHandler;  
                                /* Called on completion with error */
        DcppHandlerRoutine triggerHandler;/* Called on trigger message */
        DcppHandlerRoutine ersHandler;/* Called on Ers message */
        DcppHandlerRoutine msgHandler;/* Called on MsgOut message */
        DcppBulkTransRoutine bulkTransHandler; /* Called for bulk transfer */
        DcppHandlerRoutine bulkDoneHandler; /* Called for bulk done */
        DcppVoidPnt clientData; /* Passed to callback routines  */
        DcppTask *task;         /* The task involved            */
        bool    forgotten;      /* deliberately orphaned        */
 
/*
 *      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.
 *
 *      Also disallow the default constructor.
 */
        DcppTransaction& operator=(const DcppTransaction&);
        DcppTransaction(const DcppTransaction&);
        DcppTransaction();
 
 
    public:
        DcppTransaction(DcppTask *Task, 
                        const DcppHandlerRoutine Success= 0, 
                        const DcppHandlerRoutine Error = 0,
                        const DcppHandlerRoutine Trigger = 0,
                        const DcppHandlerRoutine Ers = 0,
                        const DcppHandlerRoutine Msg = 0,
                        const DcppVoidPnt ClientData = 0):
            checkvalue(DcppCheckData), successHandler(Success),
            errorHandler(Error), triggerHandler(Trigger),
            ersHandler(Ers), msgHandler(Msg), bulkTransHandler(0),
            bulkDoneHandler(0), clientData(ClientData), task(Task),
            forgotten(false)
        {
        };
        DcppTransaction(DcppTask *Task, 
                        const DcppHandlerRoutine Success= 0, 
                        const DcppHandlerRoutine Error = 0,
                        const DcppHandlerRoutine Trigger = 0,
                        const DcppHandlerRoutine Ers = 0,
                        const DcppHandlerRoutine Msg = 0,
                        const DcppBulkTransRoutine BulkTrans = 0,
                        const DcppHandlerRoutine BulkDone = 0,
                        const DcppVoidPnt ClientData = 0):
            checkvalue(DcppCheckData), successHandler(Success),
            errorHandler(Error), triggerHandler(Trigger),
            ersHandler(Ers), msgHandler(Msg),  
            bulkTransHandler(BulkTrans), bulkDoneHandler(BulkDone), 
            clientData(ClientData), task(Task), forgotten(false)
        {
        };
        int check () const { return checkvalue == DcppCheckData;};
 
        /* Functions to fetch the various items         */
        DcppHandlerRoutine SuccessHandler() const { return successHandler; };
        DcppHandlerRoutine TriggerHandler() const { return triggerHandler; };
        DcppHandlerRoutine ErrorHandler() const { return errorHandler; };
        DcppHandlerRoutine ErsHandler() const { return ersHandler; };
        DcppHandlerRoutine MsgHandler() const { return msgHandler; };
        DcppBulkTransRoutine BulkTransHandler() const { 
            return bulkTransHandler;}
        DcppHandlerRoutine BulkDoneHandler() const { return bulkDoneHandler;}
        DcppVoidPnt        ClientData() const { return clientData; };
        DcppTask *         Task() const { return task; };
        DcppHandlerRet     HandleEvent(StatusType * const status);
        bool Forgotten () const  { return forgotten; };
        void Forget() { forgotten = true; };
};
 
 
/*
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * DcppShared
 */
DPUBLICCLASS DcppShared {
 
    public:
        enum SharedType { 
               Create  = DITS_SHARE_CREATE, 
               Gblsec  = DITS_SHARE_GBLSEC, 
               Global  = DITS_SHARE_GLOBAL, 
               ShMem   = DITS_SHARE_SHMEM, 
               MMap    = DITS_SHARE_MMAP   
               };
 
    private:
        DitsSharedMemInfoType info;
        bool valid;
        void *address;
        SdsId Structure;
        bool free;
/*
 *      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.
 *
 *      Also disallow the default constructor.
 */
        DcppShared& operator=(const DcppShared&);
        DcppShared(const DcppShared&);
        DcppShared();
 
 
    public:
        DcppShared(
            long Size,
            StatusType *const status,
            const SharedType Type = Create,
            const int CreateIt = true,
            const char * const Name = "",
            const int Key = 0,
            void * const Address = 0
            ) : valid(false), address(0), Structure(0), free(true) {
 
            if (*status != STATUS__OK) return;
 
            // If an address was supplied, copy it (only used for some times)
            if (Address)
                address = Address;
 
            DitsDefineShared(Type, (char *)Name, Key, Size, CreateIt, &address,
                             &info, status);
            if (*status == STATUS__OK)
                valid = true;
        }
        DcppShared(
            const SdsId & Template,
            StatusType *const status,
            const SharedType Type = Create,
            const int CreateIt = true,
            const char * const Name = "",
            const int Key = 0,
            void * const Address = 0
            ) : valid(false), address(0), Structure(0), free(true) {
 
            if (*status != STATUS__OK) return;
 
            // If an address was supplied, copy it (only used for some times)
            if (Address)
                address = Address;
 
            // Create the segement 
            SdsIdType ID;
            DitsDefineSdsShared(Template, Type, (char *)Name, Key, CreateIt, 
                                &address, &info, &ID, status);
            if (*status == STATUS__OK)
            {
                // Valid return.  Remember and copy the SDS id
                valid = true;
                Structure.ShallowCopy(ID, true, false, false);
            }
        }
        DcppShared(DitsSharedMemInfoType *Info, void *Address = 0, 
                   SdsIdType ID = 0, bool Free = false) 
             :  valid(true), address(Address), Structure(0), free(Free) {
            info = *Info;
            if (ID)
                Structure.ShallowCopy(ID, Free, false, false);
        }
 
        void GetInfo(const DitsSharedMemInfoType * * const Info, 
                     StatusType * const status) const {
            if (*status != STATUS__OK) return;
            if (!valid)
                *status = DCPP__SHARENOVALID;
            else
                *Info = &info;
        }
 
        void GetInfo(DitsSharedMemInfoType * * const Info, 
                     StatusType * const status) {
            if (*status != STATUS__OK) return;
            if (!valid)
                *status = DCPP__SHARENOVALID;
            else
                *Info = &info;
        }
 
         /*
           We are safe to not have a status
           argument since SdsId will have been initialised to a null
           id.  Doing it without status makes it easier to use.  const
           and non-const versions
         */
        SdsId & GetSds () {
            return Structure;
        }
        const SdsId & GetSds () const {
            return Structure;
        }
 
        void GetAddress(const void **Address, StatusType *status) const {
            if (*status != STATUS__OK) return;
            if (!valid)
                *status = DCPP__SHARENOVALID;
            else if (!address)
                *status = DCPP__SHARENOADD; /* If created from Info 
                                               constructor and address not
                                               supplied
                                               */
            else
                *Address = address;
        }
        void GetAddress(void **Address, StatusType *status) {
            if (*status != STATUS__OK) return;
            if (!valid)
                *status = DCPP__SHARENOVALID;
            else
                *Address = address;
        }
 
        virtual ~DcppShared() {
            StatusType status = STATUS__OK;
            if (free)
                DitsReleaseShared(&info, 1, &status);
            valid = false; // Should not be necessary;
        }
        
};                                      
#endif