bpipexx  1.0.6_01
 All Classes Functions Pages
SAOTrace::BPipeX::Simple Class Reference

#include <bpipexx/bpipexx.h>

Public Member Functions

 ~Simple ()
 Destructor. More...
 
 Simple ()
 Constructor. More...
 
 Simple (const string &input, const string &output)
 Constructor specifying input and output streams. More...
 
template<typename T >
void add (HdrF< T > field)
 add a header field More...
 
template<typename T >
void add (const DpktF< T > &field)
 add a data packet field More...
 
void delete_hdrf (const char *name, size_t index=BPHdrfIdx_ALL)
 delete a header field More...
 
void delete_dpktf (const char *name, BPDataSite site=BPDSite_OUTPUT, BPipeOutput *channel=BPOutputChannel_ALL)
 delete a data packet field More...
 
bool has_hdrf (const char *name, size_t index=BPHdrfIdx_LAST)
 test if a header field exists More...
 
bool has_dpktf (const char *name)
 test if a data packet field exists More...
 
template<typename T >
T * dpktf_data (const char *name)
 get a pointer to the data in a data packet field More...
 
template<typename T >
T * hdrf_data (const char *name, size_t idx=BPHdrfIdx_LAST)
 get a pointer to the data in a header packet field More...
 
void map (int npkts=1)
 map the data packet fields onto memory. More...
 
size_t read_dpkts ()
 read in the next batch of data packets More...
 
void write_hdr ()
 write the output header More...
 
void write_dpkts (BPipeOutput *bpo=BPOutputChannel_ALL)
 write a data packet More...
 
BPipe * bpipe ()
 

Detailed Description

A simple wrapper class providing optimized access to a binary pipe object.

Creating an object and attaching to streams

The easiest means to create an object manipulating bpipe streams is to use the two argument constructor:

#include <SAOTrace/bpipexx/bpipexx.h>
using namespace SAOTrace;
BPipeX::Simple bp( "", "stdout" );

In this case it opens an output stream, but no input stream, suitable for a ray generater. For a filter, specify both streams, for a sink, specify only the input stream.

For more complex situations, don't specify any streams, and use the bpipe accessor to manipulate the underlying bpipe object directly:

BPipeX::Simple bp();
bpipe_input( bp->bpipe, "stdin" );

Manipulating Header Fields

Recall that the header accepts multiple fields with the same name.

The first step is to create a BPipeX::HdrF object, then pass it to the add method. The steps can be combined:

bp.add( BPipeX::HdrF<double>("temp", 33.2 ) );

To delete a header field, use delete_hdrf:

bp.delete_hdrf( "temp" );

Manipulating Data Packet Fields

Recall that the data packets can have only one field with a given name.

The first step is to create a BPipeX::DpktF object, then pass it to the add method. The steps can be combined:

bp.add( BPipeX::DpktF<double>("temp") );

To delete a data packet field from the output, use delete_dpktf:

bp.delete_dpktf( "temp" );

See the documentation for delete_dpktf for more complex use.

Mapping, reading and writing

After all fields are created, the packet images must be mapped:

bp.map();

To access the location in the core image for a data packet field, use dpktf_data:

double* temp_p = bp.dpktf_data<double>( "temp" );

For filters or sinks, make sure to write the header prior to outputing any data packets:

bp.write_hdr();

Use read_dpkts and write_dpkts to read and write.

Closing I/O Streams

The streams will be closed upon destruction of the BPipeX::Simple object.

Constructor & Destructor Documentation

SAOTrace::BPipeX::Simple::~Simple ( )

Destructor.

Destroy a BPipeX::Simple object, closing the associated output streams.

SAOTrace::BPipeX::Simple::Simple ( )

Constructor.

Construct the underlying bpipe object without attaching any streams

SAOTrace::BPipeX::Simple::Simple ( const string &  input,
const string &  output 
)

Constructor specifying input and output streams.

Either of the parameters may be an empty string, indicating that that stream should not be attached.

Parameters
[in]inputthe name of the input stream (may be stdin)
[in]outputthe name of the input stream (may be stdout)
Exceptions
Exceptionif it is unable to attach the streams.

Member Function Documentation

template<typename T >
void SAOTrace::BPipeX::Simple::add ( HdrF< T >  field)
inline

add a header field

For example:

bpipe.add( HdrF<double>("temperature", 33.2) );
Parameters
[in]fieldA BPipeX::HdrF object
Exceptions
Exceptionif unable to create the header field

References SAOTrace::BPipeX::HdrF< T >::data().

template<typename T >
void SAOTrace::BPipeX::Simple::add ( const DpktF< T > &  field)
inline

add a data packet field

For example:

bpipe.add( DpktF<double>("smile") );
Parameters
[in]fieldA BPipeX::DpktF object
Exceptions
Exceptionif unable to create the data packet field or the field exists with a different data type.
void SAOTrace::BPipeX::Simple::delete_dpktf ( const char *  name,
BPDataSite  site = BPDSite_OUTPUT,
BPipeOutput *  channel = BPOutputChannel_ALL 
)

delete a data packet field

Deletes the specified data packet field. By default the field is removed from the output image of all output channels. Set the site parameter to change the data site or the channel parameter to specify an alternate output channel

Parameters
[in]namethe name of the field to delete
[in]sitethe optional data site in which to delete it. This may be one of
  • BPDSite_INPUT
  • BPDSite_CORE, or
  • BPDSite_OUTPUT
[in]channeloptional channel output channel to delete from
Exceptions
Exceptionif there is an error
void SAOTrace::BPipeX::Simple::delete_hdrf ( const char *  name,
size_t  index = BPHdrfIdx_ALL 
)

delete a header field

Deletes the specified header field. By default it will delete all header fields with the given name. Set the index parameter to either the index of field to delete, or to BPHdrfIdx_LAST to delete the last one.

Parameters
[in]namethe name of the field to delete
[in]indexthe optional index of the field to delete.
Exceptions
Exceptionif there is an error
template<typename T >
T* SAOTrace::BPipeX::Simple::dpktf_data ( const char *  name)
inline

get a pointer to the data in a data packet field

For example:

double* temp_p = bpipe.dpktf_data<double>( "temp" );
Template Parameters
Tthe type of the stored data.
Parameters
[in]namethe name of the data packet field.
bool SAOTrace::BPipeX::Simple::has_dpktf ( const char *  name)

test if a data packet field exists

Parameters
[in]namethe name of the field
Returns
true if the field exists
bool SAOTrace::BPipeX::Simple::has_hdrf ( const char *  name,
size_t  index = BPHdrfIdx_LAST 
)

test if a header field exists

Parameters
[in]namethe name of the field
[in]indexthe optional index of the field to delete. Defaults to BPHdrfIdx_LAST
Returns
true if the field exists
template<typename T >
T* SAOTrace::BPipeX::Simple::hdrf_data ( const char *  name,
size_t  idx = BPHdrfIdx_LAST 
)
inline

get a pointer to the data in a header packet field

For example:

double* temp_p = bpipe.hdrf_data<double>( "temp" );
Template Parameters
Tthe type of the stored data.
Parameters
[in]namethe name of the data packet field.
[in]idxthe index of the field. Defaults to the last one.
void SAOTrace::BPipeX::Simple::map ( int  npkts = 1)

map the data packet fields onto memory.

This function maps the data packet fields onto memory and allocates space for the images.

Parameters
[in]npktsthe optional number of packets to allocate space for. defaults to 1
Exceptions
Exceptionif it is unable to allocate the image.
size_t SAOTrace::BPipeX::Simple::read_dpkts ( )

read in the next batch of data packets

Read in the number of data packets specified by the map method.

Returns
the number of packets read
Exceptions
Exceptionif there is an error reading the input stream
void SAOTrace::BPipeX::Simple::write_dpkts ( BPipeOutput *  bpo = BPOutputChannel_ALL)

write a data packet

Writes a data packet to one or all output channels.

Parameters
[in]bpothe optional output channel to write to. Defaults to writing to all output channels.
Exceptions
Exceptionif there is an error
void SAOTrace::BPipeX::Simple::write_hdr ( )

write the output header

Writes header information to the output channels

Exceptions
Exceptionif there is an error

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