AAO DRAMA/DRAMA2 C++ Interface
Public Member Functions | Protected Member Functions | List of all members
drama::BulkData Class Reference

Detailed Description

Defines and optionally creates a shared memory section.

Shared memory sections are used by DRAMA in the handling of bulk data transfers.

If Type is set to ShareType::Create, then this class's main constructor creates a temporary shared memory section of the size specified in some suitable form for the system it is running on. The caller has no control over the details of the shared memory section. In this case, the Name and Key arguments, and any preset value at the location specified by the Address argument are all ignored. A new section will be created and mapped.

VxWorks: The mapped section is just a section of memory, starting at a specified address. Type should be ShareType::Global. Name should be an empty string, and Key is ignored. If Create is specified, Address is ignored, and a suitably sized area of memory is allocated. If Create is passed as false, then Address should contain the address of the memory section in question. Under VxWorks, this is what is generated by ShareType::Default.

UNIX: The mapped section can be created as System V shared memory, in which case Type should be ShareType::SHMem , or as a file accessed through mmap(), in which case Type should be ShareType::MMap. If Type is ShareType::SHMem, Key specifies the identifier for the shared memory and Name should be an empty string. If Type is ShareType::MMap, Name should be the full name of the file, and Key is ignored. Address is ignored in both cases. On UNIX, one of these types will be what is provided by ShareType::Default.

Author
Tony Farrell, AAO
Revision
1.45
Date
22-Feb-2016 14:09:57+11
Id
ACMM:Drama2/drama/bulkdata.hh,v 1.45 22-Feb-2016 14:09:57+11 tjf

#include "bulkdata.hh"

Inheritance diagram for drama::BulkData:
drama::BulkDataArg drama::BulkDataSds drama::BulkDataArgSds

Public Member Functions

 BulkData ()
 Default constructor. More...
 
 BulkData (std::weak_ptr< Task > theTask, long Size, ShareType type=ShareType::Create, bool Create=true, bool DeleteOnDestruct=true, void *Address=nullptr, const std::string &Name="", int Key=0)
 Define a bulk data shared memory segment of the specified type for use with DRAMA 2 methods which can send bulk data. More...
 
 BulkData (std::weak_ptr< Task > theTask, const DitsBulkReportInfoType &info)
 Define a bulk data shared memory segment based on a DitsBulkReportInfoType item. More...
 
 BulkData (const BulkData &source)=delete
 Copy constructor - deleted. More...
 
 BulkData (BulkData &&source) noexcept
 Move copy constructor. More...
 
virtual ~BulkData ()
 Destructor. More...
 
template<typename T >
T * Data (unsigned long *nitems=nullptr)
 Return a pointer to the actual data. More...
 
DitsSharedMemInfoType & GetDitsSharedMemInfo ()
 Return a reference to the DitsSharedMemInfoType object managed by this. More...
 
BulkDataoperator= (const BulkData &rhs)=delete
 Assignment operator - deleted. More...
 
BulkDataoperator= (BulkData &&rhs) noexcept
 Move assignment operator. More...
 

Protected Member Functions

void * RawDataAddr () const
 Returns the raw address of the data. More...
 
unsigned long SizeBytes () const
 Return the size of the data in bytes. More...
 

Constructor & Destructor Documentation

drama::BulkData::BulkData ( )
inline

Default constructor.

Items created this way are only suitable as a target for Move Assignment and Move Copy operations. Attempts to access the memory item will throw an exception.

drama::BulkData::BulkData ( std::weak_ptr< Task theTask,
long  Size,
ShareType  type = ShareType::Create,
bool  Create = true,
bool  DeleteOnDestruct = true,
void *  Address = nullptr,
const std::string &  Name = "",
int  Key = 0 
)

Define a bulk data shared memory segment of the specified type for use with DRAMA 2 methods which can send bulk data.

The parameters for this routine are used quite differently in the different systems for which DRAMA is implemented, and these system dependent details are described in more detail below.

Parameters
theTaskThe DRAMA Task we are part of. This is passed by pointer, but BulkData is not taking ownership of the subject object, which must continue to exist until the BulkData object is destroyed.
SizeThe size of the segment in bytes
typeThe type of the shared memory item. See class description for more details.
CreateIf true, the memory section does not actually exist and this routine is to create it.
DeleteOnDestructIf set true, then the shared memory segment will be deleted when the BulkData item destructor is invoked.
AddressOn systems with global address spaces, eg. VxWorks, the address of the memory is enough to specify it completely - together with its size. In any case, if the section is already mapped, this argument must specify the address at which it is mapped. If the section is created by this routine, it will ignored.
NameUsed to identify the mapped section on some machines. On UNIX, for example, if mapped files are used, this is the file name in question. If Name is not actually used on the current system it should be passed as an empty string.
KeyOn some systems, this is an alternative way of specifying the mapped section. For example, if System V shared memory is used under UNIX, this is the identifier for that shared memory.
drama::BulkData::BulkData ( std::weak_ptr< Task theTask,
const DitsBulkReportInfoType &  info 
)

Define a bulk data shared memory segment based on a DitsBulkReportInfoType item.

This constructor is not normally invoked by user code, instead it is used by the BulkDataArg class implementation.

This constructor is used to create a drama::BulkData item from details that have been returned by DitsBulkArgInfo(). These are used with the DRAMA C interface to allow action code to access bulk data arguments. This class provides a C++ interfaces.

The memory is not released or deleted when this item is destroyed, through the task which sent the message containing the bulk data is told that the item has been released

Parameters
theTaskThe DRAMA Task we are part of. This is passed by pointer, but BulkData is not taking ownership of the subject object, which must continue to exist until the BulkData object is destroyed.
infoDetails returned by DitsBulkArgInfo().
virtual drama::BulkData::~BulkData ( )
inlinevirtual

Destructor.

Release access to the shared memory.

The shared memory segment will be deleted if the DeleteOnDestruct flag to the constructor was set true.

drama::BulkData::BulkData ( const BulkData source)
delete

Copy constructor - deleted.

A Move constructor is available and deals with most cases of interest.

drama::BulkData::BulkData ( BulkData &&  source)
inlinenoexcept

Move copy constructor.

Often optimized out using the "copy elision" rule.

Member Function Documentation

template<typename T >
T* drama::BulkData::Data ( unsigned long *  nitems = nullptr)
inline

Return a pointer to the actual data.

Will throw an exception if the shared memory segment has not been constructed correctly (e.g. it was generated by the default constructor - which can only be used as a target of a move assignment or move-copy operation.)

Template Parameters
TThe type of the data item. This needs to be a POD type, if not, compile will fail with a static assertion.
Parameters
nitemsIf non-null, the number of items which can fit in the shared memory is returned here.

References DramaTHROW.

DitsSharedMemInfoType& drama::BulkData::GetDitsSharedMemInfo ( )
inline

Return a reference to the DitsSharedMemInfoType object managed by this.

Will throw an exception if the shared memory segment has not been constructed correctly (e.g. it was generated by the default constructor - which can only be used as a target of a move assignment or move-copy operation.)

References DramaTHROW.

BulkData& drama::BulkData::operator= ( const BulkData rhs)
delete

Assignment operator - deleted.

A Move assignment operator is available and deals with most cases of interest.

Referenced by drama::BulkDataArg::operator=().

BulkData& drama::BulkData::operator= ( BulkData &&  rhs)
inlinenoexcept

Move assignment operator.

Often optimized out using the "copy elision" rule.

void* drama::BulkData::RawDataAddr ( ) const
inlineprotected

Returns the raw address of the data.

unsigned long drama::BulkData::SizeBytes ( ) const
inlineprotected

Return the size of the data in bytes.


The documentation for this class was generated from the following file:

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 15:57:52 for AAO DRAMA/DRAMA2 C++ Interface by doxygen 1.8.10