DRAMA C++ Intro   Class Hierarchy   Alphabetical List of types   List of Classes   File List   Class Member Index   File Members Index   Related Pages  

dcpp.h File Reference


Detailed Description

#include "DitsTypes.h"
#include "DitsInteraction.h"
#include "DitsBulk.h"
#include "sds.h"
#include "arg.h"
#include "dcpp_err.h"

Go to the source code of this file.

Compounds

class  DcppBuffers
 A structure representing message buffer sizes. More...

class  DcppShared
 This is used to create and represent a shared memory segment. More...

class  DcppTransaction
 A type used to connect DcppHandler and DcppTask. More...


Typedefs

typedef void * DcppVoidPnt
 A pointer to void.

typedef DcppVoidPntDcppVoidPntPnt
 A pointer to a pointer to void.

typedef DcppHandlerRet(* DcppHandlerRoutine )(DcppVoidPnt ClientData, StatusType *status)
 Type for call backs when messages arrive.

typedef void(* DcppBulkTransRoutine )(unsigned long Transferred, unsigned long Total, DcppVoidPnt ClientData, StatusType *status)
 Type for call backs for DITS_REA_TRANSFERRED messages.


Enumerations

enum  DcppHandlerRet { DcppReschedule, DcppNotHandled, DcppFinished }
 Type returns by various routines to indicate what is to happen next. More...


Functions

DcppHandlerRet DcppDispatch (StatusType *const status)
 Basic message handler function.

void DcppUfaceCtxEnable (StatusType *const status)
 Enable handling of messages started in UFACE context.

void DcppSpawnKickArg (DitsTransIdType transid, SdsId *id, StatusType *status)
 Create an argument structure used when kick actions which spawn.

void DcppSpawnKickArgUpdate (DitsTransIdType transid, const SdsId *id, StatusType *status)
 Update an argument structure used when kick actions which spawn.

void DcppForgetAll (void *client_data, int taskExit, StatusType exitStatus, StatusType *const status)
 Forget all transaction assocaited with the current action.

void DcppVarArgsToSds (int count, Arg &ArgId, StatusType *status, va_list args)
 Convert a variable argument list into an SDS structure.


Variables

const unsigned DcppNodeNameLen = 100
 Maximum Node name length.

const unsigned DcppArgumentLen = 200
 Maximum Node name length.

const long int DcppCheckData = 0x0e0e0e0e
 Internal use only.


Typedef Documentation

typedef void(* DcppBulkTransRoutine)(unsigned long Transferred, unsigned long Total, DcppVoidPnt ClientData, StatusType *status)
 

Type for call backs for DITS_REA_TRANSFERRED messages.

Similar to DcppHandlerRet, but for entries with a reason of DITS_REA_TRANSFERRED only. Allow us to pass in the Transferred and Total bytes.

Parameters:
Transferred  Set to the number of bytes transferred so far.
Total  The total number of bytes to be transferred.
ClientData  Use data.
status  Inherited status.

typedef DcppHandlerRet(* DcppHandlerRoutine)(DcppVoidPnt ClientData, StatusType *status)
 

Type for call backs when messages arrive.

A type for functions which are invoked as a callback when a message comes in. Arguments of this type are used throughout the Dcpp functions.

Such functions Should return either DcppReschedule is it initiated a new transactions or DcppFinished if it did not.

Parameters:
ClientData  user data
Status  Inherited status.

typedef void* DcppVoidPnt
 

A pointer to void.

typedef DcppVoidPnt* DcppVoidPntPnt
 

A pointer to a pointer to void.


Enumeration Type Documentation

enum DcppHandlerRet
 

Type returns by various routines to indicate what is to happen next.

Various routines return one of these values to indicate what the action should do.

Enumeration values:
DcppReschedule  More messages expected, should reschedule.
DcppNotHandled  Only from DccpDisptach, message not handled.
DcppFinished  Have finished, action can complete.


Function Documentation

DcppHandlerRet DcppDispatch StatusType *const    status
 

Basic message handler function.

This function will examine the details of a message which has caused an entry to a DRAMA reschedule handler or UFACE handler. If this message was started by DcppTask, then it will dispatch to the DcppTask to handle the message. DcppFinished/DcppReschedule is returned by DcppTask. DcppNotHandled is returned if DcppDispatch if the message was not started by DcppTask.

Parameters:
status  Inherited status.

void DcppForgetAll void *    client_data,
int    taskExit,
StatusType    exitStatus,
StatusType *const    status
 

Forget all transaction assocaited with the current action.

This routine can be invoked to forget all transactions associated with the current action. This is set up such that it can be invoked as an action end routine (see DitsPutActEndRoutine()). For example:

  DitsPutActEndRoutine(DcppForgetAll, 0, 0, 0, status);

For all Dcpp transactions, the behaviour is as if all outstanding transactions were invoked using ObeyForget() etc. This ensures the success and error routines are invoked by the orphan handler, if any.

taskExit and exitStatus are ignored.

This function should not be invoked by an orphan handler action and must not be invoked in uface context.

Parameters:
client_data  Was supplied to DitsPutActEndRoutine
taskExit  Is the task exiting
exitStatus  If exiting, the exit status
status  Inherited status

void DcppSpawnKickArg DitsTransIdType    transid,
SdsId   id,
StatusType *    status
 

Create an argument structure used when kick actions which spawn.

Actions which spawn (allowing multiple actions of the same name) must be kicked by specifing an argument structure which allows the target task to determine which invocation of the action should be kicked.

This can be done by either specifing the action index (which the subsidary task can get using DitsGetActIndex()) as an argument named "KickByIndex" or anther task using the transaction id (as known by the parent action of this action), as wraped up in an argument by this call.

Note, arguments to the kick itself can be added to the argument created here, using standard ArgPut functions. Also, it is possible to change the transaction id in this structure using DcppSpawnKickArgUpdate().

The Dcpp versions of these functions allow the use of SdsId's to contain the SDS ID, but otherwise just invoked the Dits versions.

See also:
DitsSpawnKickArg , DcppSpawnKickArgUpdate
Parameters:
transid  The transaction id.
id  The SDS ID is returned here using SdsId::ShallowCopy (and hence deleting any old SDS ID stored here)
status  Modified status.

void DcppSpawnKickArgUpdate DitsTransIdType    transid,
const SdsId   id,
StatusType *    status
 

Update an argument structure used when kick actions which spawn.

Actions which spawn (allowing multiple actions of the same name) must be kicked by specifing an argument structure which allows the target task to determine which invocation of the action should be kicked.

This can be done by either specifing the action index (which the subsidary task can get using DitsGetActIndex()) as an argument named "KickByIndex" or anther task using the transaction id (as known by the parent action of this action), as wraped up in an argument by this call. This routine can be used to change the transaction id in such argument structure.

It can also be used to add such and item to an existing structure, which it does if it does not already exist within the structure. Note that in this case, if an item named "KickByIndex" is found, it is deleted. The add if is does not exist feature only works for internal SDS items, whilst the update only feature will also work for external SDS items.

The Dcpp versions of these functions allow the use of SdsId's to contain the SDS ID, but otherwise just invoked the Dits versions.

See also:
DitsSpawnKickArgUopdate , DcppSpawnKickArg
Parameters:
transid  The transaction id.
id  The SDS ID contain here is modified. If an item named KickByTransId does not exist, it will be created. The value of this item (regardless of if created) will be set to the transaction id
status  Modified status.

void DcppUfaceCtxEnable StatusType *const    status [inline]
 

Enable handling of messages started in UFACE context.

This routine allows the DcppTask routines to be invoked from Uface context. We simply specify DcppDispatch as the Uface routine, ignoring the returned value

Parameters:
status  Inherited status.

void DcppVarArgsToSds int    count,
Arg   ArgId,
StatusType *    status,
va_list    args
 

Convert a variable argument list into an SDS structure.

This function is invoked internally in Dcpp - through can be used from outside if need be. It tasks a variable argument structure and converts it to an SDS structure of the form Argumentd where d is replaced by the number of the argument

Parameters:
count  The number of arguments. If negative, then args contains a single character string which contains a space separated list of values
arg  The values will be put into this SDS structure
status  Modified status
args  The variable argument list. Should be a list of character strings.


Variable Documentation

const unsigned DcppArgumentLen = 200
 

Maximum Node name length.

const long int DcppCheckData = 0x0e0e0e0e
 

Internal use only.

const unsigned DcppNodeNameLen = 100
 

Maximum Node name length.


Click here for the DRAMA home page and here for the AAO home page.

For more information, contact tjf@aaoepp.aao.gov.au 

Generated on Tue Nov 3 09:09:56 2009 for AAO DRAMA C++ Interfaces by doxygen 1.2.18