ROSE  0.9.10.91
Classes | Public Types | Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | List of all members
Rose::BinaryAnalysis::SerialIo Class Referenceabstract

Description

Base class for binary state input and output.

A SerialIo object writes analysis results to a file, or initializes analysis results from a file. It handles such things as not storing the same object twice when referenced by different pointers, storing derived objects through base-class pointers, and providing progress reports.

The file in which the state is stored is accessed sequentially, making it suitable to send output to a stream or read from a stream. This also means that most of the interface for these objects has no need to be thread-safe, although the progress-reporting part of the API is thread-safe.

As objects are written to the output stream, they are each preceded by a object type identifier. These integer type identifiers are available when reading from the stream in order to decide which type of object to read next.

I/O errors are reported by throwing an Exception. Errors thrown by underlying layers, such as Boost, are caught and rethrown as Exception in order to simplify this interface.

Here's an example of how to write a partitioner followed by a vector of doubles to a state file using XML format:

using namespace Rose::BinaryAnalysis;
std::vector<double> myVector = ...;
const SerialIo::Savable myVectorTypeId = SerialIo::USER_DEFINED; // maybe add some constant
P2::Partitioner partitioner = ....;
boost::filesystem::path fileName = "....";
try {
saver->mlog[INFO] <<"saving state to " <<fileName;
saver->format(SerialIo::XML);
saver->open(fileName);
saver->savePartitioner(partitioner);
saver->saveObject(myVectorTypeId, myVector);
saver->close();
saver->mlog[INFO] <<"; saved\n";
} catch (const SerialIo::Exception &e) {
saver->mlog[ERROR] <<e.what() <<"\n";
}

Reading is similar:

SerialInput::Ptr loader = SerialInput::instance();
try {
loader->mlog[INFO] <<"loading state from " <<fileName;
loader->format(SerialIo::XML);
loader->open(fileName);
partitioner = loader->loadPartitioner();
myVector = loader->loadObject<P2::Partitioner>(myVectorTypeId);
loader->close();
loader->mlog[INFO] <<"; loaded\n";
} catch (const SerialIo::Exception &e) {
loader->mlog[ERROR] <<e.what() <<"\n";
}

Definition at line 110 of file BinarySerialIo.h.

#include <BinarySerialIo.h>

Inheritance diagram for Rose::BinaryAnalysis::SerialIo:
Inheritance graph
[legend]
Collaboration diagram for Rose::BinaryAnalysis::SerialIo:
Collaboration graph
[legend]

Classes

class  Exception
 Errors thrown by this API. More...
 

Public Types

enum  Format {
  BINARY,
  TEXT,
  XML
}
 Format of the state file. More...
 
enum  Savable {
  NO_OBJECT = 0x00000000,
  PARTITIONER = 0x00000001,
  AST = 0x00000002,
  END_OF_DATA = 0x0000fffe,
  ERROR = 0x0000ffff,
  USER_DEFINED = 0x00010000,
  USER_DEFINED_LAST = 0xffffffff
}
 Types of objects that can be saved. More...
 
typedef Sawyer::SharedPointer< SerialIoPtr
 Reference-counting pointer. More...
 

Public Member Functions

virtual ~SerialIo ()
 Destructor. More...
 
virtual void open (const boost::filesystem::path &)=0
 Attach a file. More...
 
virtual void close ()=0
 Detach a file. More...
 
bool isOpen () const
 Whether a file is attached. More...
 
Savable objectType () const
 Type ID for next object. More...
 
Format format () const
 Property: File format. More...
 
void format (Format)
 Property: File format. More...
 
Progress::Ptr progress () const
 Property: Progress reporter. More...
 
void progress (const Progress::Ptr &)
 Property: Progress reporter. More...
 
- Public Member Functions inherited from Sawyer::SharedObject
 SharedObject ()
 Default constructor. More...
 
 SharedObject (const SharedObject &)
 Copy constructor. More...
 
virtual ~SharedObject ()
 Virtual destructor. More...
 
SharedObjectoperator= (const SharedObject &)
 Assignment. More...
 

Static Public Attributes

static Sawyer::Message::Facility mlog
 Message facility. More...
 

Protected Member Functions

void setIsOpen (bool b)
 
void objectType (Savable)
 

Protected Attributes

Sawyer::ProgressBar< size_t > progressBar_
 
int fd_
 

Member Typedef Documentation

Reference-counting pointer.

Definition at line 113 of file BinarySerialIo.h.

Member Enumeration Documentation

Format of the state file.

Enumerator
BINARY 

Binary state files are smaller and faster than the other formats, but are not portable across architectures.

TEXT 

Textual binary state files use a custom format (Boost serialization format) that stores the data as ASCII text.

They are larger and slower than binary files but not as large and slow as XML or JSON files. They are portable across architectures.

XML 

The states are stored as XML, which is a very verbose and slow format.

Avoid using this if possible.

Definition at line 116 of file BinarySerialIo.h.

Types of objects that can be saved.

Enumerator
NO_OBJECT 

Object type for newly-initialized serializers.

PARTITIONER 

Rose::BinaryAnalysis::Partitioner2::Partitioner.

AST 

Abstract syntax tree.

END_OF_DATA 

Marks the end of the data stream.

ERROR 

Marks that the stream has encountered an error condition.

USER_DEFINED 

First user-defined object number.

USER_DEFINED_LAST 

Last user-defined object number.

Definition at line 127 of file BinarySerialIo.h.

Constructor & Destructor Documentation

virtual Rose::BinaryAnalysis::SerialIo::~SerialIo ( )
virtual

Destructor.

Since I/O objects are reference counted, the user should not invoke the destructor explicitly; it will be called automatically when the last reference to this object goes away.

The destructor closes any attached file but does not throw exceptions. Therefore, it is better to always explicitly close an I/O object before destroying it.

Member Function Documentation

Format Rose::BinaryAnalysis::SerialIo::format ( ) const

Property: File format.

This property specifies the file format of the data. It can only be set for output, and only before the output file is opened.

Thread safety: This method is thread-safe.

void Rose::BinaryAnalysis::SerialIo::format ( Format  )

Property: File format.

This property specifies the file format of the data. It can only be set for output, and only before the output file is opened.

Thread safety: This method is thread-safe.

Progress::Ptr Rose::BinaryAnalysis::SerialIo::progress ( ) const

Property: Progress reporter.

A progress reporting object can be specified in which case the I/O operations will update this object. I/O objects are created with an initial progress reporter, but this can be changed at any time.

Thread safety: This method is thread-safe.

Referenced by Rose::BinaryAnalysis::SerialOutput::saveObject().

void Rose::BinaryAnalysis::SerialIo::progress ( const Progress::Ptr )

Property: Progress reporter.

A progress reporting object can be specified in which case the I/O operations will update this object. I/O objects are created with an initial progress reporter, but this can be changed at any time.

Thread safety: This method is thread-safe.

virtual void Rose::BinaryAnalysis::SerialIo::open ( const boost::filesystem::path &  )
pure virtual

Attach a file.

When opening an output stream, the file is created or truncated; when opening an input stream the file must already exist. If a file is already attached, then the previous file is closed first before this new one is opened.

Throws an Exception if the file cannot be attached or the previous if any, cannot be closed.

Thread safety: This method is not thread-safe.

Implemented in Rose::BinaryAnalysis::SerialInput, and Rose::BinaryAnalysis::SerialOutput.

virtual void Rose::BinaryAnalysis::SerialIo::close ( )
pure virtual

Detach a file.

If a file is attached to this I/O object, that file is closed and this object is set to its detached state. This is a no-op if no file is attached.

Throws an Exception if the file cannot be detached.

The close method is automatically called during object destruction, although its exceptions are suppressed in that situation.

Thread safety: This method is not thread-safe.

Implemented in Rose::BinaryAnalysis::SerialInput, and Rose::BinaryAnalysis::SerialOutput.

bool Rose::BinaryAnalysis::SerialIo::isOpen ( ) const

Whether a file is attached.

Returns true if this I/O object is attached to a file.

Thread safety: This method is thread-safe.

Referenced by Rose::BinaryAnalysis::SerialOutput::saveObject().

Savable Rose::BinaryAnalysis::SerialIo::objectType ( ) const

Type ID for next object.

When using an input stream, this returns the type ID for the next object to be read from the stream. When using an output stream, it's the type of the object that was last written.

Referenced by Rose::BinaryAnalysis::SerialOutput::saveObject().

Member Data Documentation

Sawyer::Message::Facility Rose::BinaryAnalysis::SerialIo::mlog
static

Message facility.

Definition at line 170 of file BinarySerialIo.h.


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