ActionThread TActionViaFunctor

SendBulkTrigger() [1/2] void drama::MessageHandler::SendBulkTrigger ( BulkData *  arg, DitsTransIdType *  transId, bool  isSds, unsigned  notifyBytes = 1024 *1024  ) inherited Send a bulk data trigger message to the parent action. This method sends a trigger message (see SendTrigger()) with a bulk data argument. The trigger message has an amount of shared memory associated with it, created as a drama::BulkData object. The bulk data is passed as efficiently as possible to the target task, and may not need to be copied at all (if on the same machine). If the bulk data contains an exported SDS item, then the target task can receive the bulk data without doing any more work. Alternatively, and required if SDS is not involved, the target task can use various inquiry functions to handle it in a special way. Sending of bulk data involves creating an DRAMA message transaction and this routine returns the associated transaction id. The sending action should receive additional reschedule events with an entry reason of EntryCode::BulkTransferred indicating the progress of the transfer. It will also receive an entry with a reason of EntryCode::BulkDone when the target task releases the shared memory. When processing a EntryCode::BulkTransferred, you can then call GetEntry().GetBulkInfo() to retrieve details of the transfer. The reception of EntryCode::BulkTransferred messages are dependent on the behavour of the target task. If it is a local task, then these mesages are recevid each time it calls drama::BulkDataArg::Report(). If the target task is remote, these update messages are sent by the local IMP transmitter task at a rate determined by it. If NotifyBytes is non-zero it indicates a hint to the target about the rate at which these notifications are requested. You should not delete the shared memory yourself until get the first message using one of these codes. When you get EntryCode::BulkDone you are free to reuse all the shared memory as the target task has finished accessing the shared memory. You can reuse parts of the shared memory early by making use of information in GetEntry().GetBulkInfo() to determine what parts of the bulk data have been used. If the target task is local, then EntryCode::BulkDone is received when the target task action entry returns or if in the case where the the task invokes DitsBulkArgInfo(3)(), when it has called DitsBulkArgRelease(3)(). If the target task is remote, then EntryCode::BulkDone is received when the local transmitter task has finished forwarding the data to the remote machine. As a result, in the remote task case, you are not notified when the target task has finished accessing the data, just when it is safe for you to re-use the local shared memory. Note Only valid if invoked in the contact of MessageReceived() being invoked for an Obey or Kick message. Parameters arg The Bulk Data segment to be the argument to the trigger message. transId Transaction id for the transaction started. This will be unique (any one time - they are reused) and allows the application to distinguish multiple different outstanding trigger replies. If specified as a nullptr, then no replies be received and you won't know when the transfer is complete. isSds Does arg contain an SDS item? If true, the target task can access the item as an argument using using SDS in the normal way If false, the shared memory contains data in an application private format and DRAMA makes no attempt to interpret it. notifyBytes If non-zero, it indicates your action should be notified (using EntryCode::BulkTransferred entries) every time the specified number of bytes are transferred. Note the this effect is somewhat dependent on the target task behavior and you may only receive the final EntryCode::BulkDone message. Referenced by drama::MessageHandler::SendBulkTrigger().