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

Classes | Typedefs | Enumerations | Functions | Variables
dcpp.h File Reference
#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.

Classes

class  DcppBuffers
 A structure representing message buffer sizes. More...
 
class  DcppTransaction
 A type used to connect DcppHandler and DcppTask. More...
 
class  DcppShared
 This is used to create and represent a shared memory segment. More...
 

Typedefs

typedef void * DcppVoidPnt
 A pointer to void. More...
 
typedef DcppVoidPntDcppVoidPntPnt
 A pointer to a pointer to void. More...
 
typedef DcppHandlerRet(* DcppHandlerRoutine) (DcppVoidPnt ClientData, StatusType *status)
 Type for call backs when messages arrive. More...
 
typedef void(* DcppBulkTransRoutine) (unsigned long Transferred, unsigned long Total, DcppVoidPnt ClientData, StatusType *status)
 Type for call backs for DITS_REA_TRANSFERRED messages. More...
 

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. More...
 
void DcppUfaceCtxEnable (StatusType *const status)
 Enable handling of messages started in UFACE context. More...
 
void DcppSpawnKickArg (DitsTransIdType transid, SdsId *id, StatusType *status)
 Create an argument structure used when kick actions which spawn. More...
 
void DcppSpawnKickArgUpdate (DitsTransIdType transid, const SdsId *id, StatusType *status)
 Update an argument structure used when kick actions which spawn. More...
 
void DcppForgetAll (void *client_data, int taskExit, StatusType exitStatus, StatusType *const status)
 Forget all transaction assocaited with the current action. More...
 
void DcppVarArgsToSds (int count, Arg &ArgId, StatusType *status, va_list args)
 Convert a variable argument list into an SDS structure. More...
 

Variables

const unsigned DcppNodeNameLen = 100
 Maximum Node name length. More...
 
const unsigned DcppArgumentLen = 200
 Maximum Node name length. More...
 
const unsigned DcppMaxArgs = 9999
 
const unsigned DcppArgNameLen = 13
 
const long int DcppCheckData = 0x0e0e0e0e
 Internal use only. More...
 

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
TransferredSet to the number of bytes transferred so far.
TotalThe total number of bytes to be transferred.
ClientDataUse data.
statusInherited 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
ClientDatauser data
StatusInherited status.
typedef void* DcppVoidPnt

A pointer to void.

A pointer to a pointer to void.

Enumeration Type Documentation

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.

Enumerator
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
statusInherited status.

Referenced by DcppUfaceCtxEnable().

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:

1 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_dataWas supplied to DitsPutActEndRoutine
taskExitIs the task exiting
exitStatusIf exiting, the exit status
statusInherited 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
transidThe transaction id.
idThe SDS ID is returned here using SdsId::ShallowCopy (and hence deleting any old SDS ID stored here)
statusModified status.

Referenced by DcppTask::Obey(), and DcppTask::ObeyForget().

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
transidThe transaction id.
idThe 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
statusModified status.

Referenced by DcppTask::Obey(), and DcppTask::ObeyForget().

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
statusInherited status.

References DcppDispatch().

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
countThe number of arguments. If negative, then args contains a single character string which contains a space separated list of values
argThe values will be put into this SDS structure
statusModified status
argsThe 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.

Referenced by DcppTransaction::check().

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@aao.gov.au 

Generated on Mon Feb 22 2016 13:58:31 for AAO DRAMA C++ Interfaces by doxygen 1.8.10