Rose::BinaryAnalysis::SerialIo Class Reference

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;
namespace P2 = Rose::BinaryAnalysis::Partitioner2;
std::vector<double> myVector = ...;
const SerialIo::Savable myVectorTypeId = SerialIo::USER_DEFINED; // maybe add some constant
P2::Partitioner::Ptr partitioner = ....;
boost::filesystem::path fileName = "....";
SerialOutput::Ptr saver = SerialOutput::instance();
 
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<std::vector<double> >(myVectorTypeId);
    loader->close();
    loader->mlog[INFO] <<"; loaded\n";
} catch (const SerialIo::Exception &e) {
    loader->mlog[ERROR] <<e.what() <<"\n";
}

Definition at line 114 of file SerialIo.h.

#include <Rose/BinaryAnalysis/SerialIo.h>

Inheritance diagram for Rose::BinaryAnalysis::SerialIo:

Collaboration diagram for Rose::BinaryAnalysis::SerialIo:

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...
using	Ptr = SerialIoPtr
	Reference counting pointer.

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

Static Public Member Functions
static Savable	userSavable (unsigned offset)
	Create a new Savable enum constant.

Static Public Attributes
static Sawyer::Message::Facility	mlog
	Message facility.

Protected Member Functions
void	setIsOpen (bool b)
void	objectType (Savable)

Protected Attributes
Sawyer::ProgressBar< size_t >	progressBar_
int	fd_

Member Typedef Documentation

Ptr

using Rose::BinaryAnalysis::SerialIo::Ptr = SerialIoPtr

Reference counting pointer.

Definition at line 117 of file SerialIo.h.

Member Enumeration Documentation

Format

enum Rose::BinaryAnalysis::SerialIo::Format

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 120 of file SerialIo.h.

Savable

enum Rose::BinaryAnalysis::SerialIo::Savable

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 131 of file SerialIo.h.

Constructor & Destructor Documentation

SerialIo()

Rose::BinaryAnalysis::SerialIo::SerialIo ( )

inlineprotected

Definition at line 166 of file SerialIo.h.

~SerialIo()

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

userSavable()

static Savable Rose::BinaryAnalysis::SerialIo::userSavable ( unsigned  offset )

static

Create a new Savable enum constant.

This is a convenience function to create a new Savable constant which is an offset from USER_DEFINED.

format() [1/2]

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.

format() [2/2]

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() [1/2]

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::SerialInput::loadObject(), and Rose::BinaryAnalysis::SerialOutput::saveObject().

progress() [2/2]

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.

open()

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::SerialOutput, and Rose::BinaryAnalysis::SerialInput.

close()

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::SerialOutput, and Rose::BinaryAnalysis::SerialInput.

isOpen()

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::SerialInput::loadObject(), and Rose::BinaryAnalysis::SerialOutput::saveObject().

objectType()

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::SerialInput::loadObject(), and Rose::BinaryAnalysis::SerialOutput::saveObject().

Member Data Documentation

progressBar_

Sawyer::ProgressBar<size_t> Rose::BinaryAnalysis::SerialIo::progressBar_

protected

Definition at line 157 of file SerialIo.h.

fd_

int Rose::BinaryAnalysis::SerialIo::fd_

protected

Definition at line 163 of file SerialIo.h.

mlog

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

static

Message facility.

Definition at line 175 of file SerialIo.h.

---

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

• SerialIo.h