Rose::BinaryAnalysis::SerialIo Class Reference

Description

Extension of the base SerialIo class defined in BasicTypes.h.

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

#include <Rose/BinaryAnalysis/SerialIo.h>

Inheritance diagram for Rose::BinaryAnalysis::SerialIo:

Collaboration diagram for Rose::BinaryAnalysis::SerialIo:

Classes
class	Deserializer
	Interface for deserializer implementations. More...
struct	SerializationRegistration
class	Serializer
	Interface for serializer implementations. More...

Public Types
using	Ptr = SerialIoPtr
	Reference counting pointer.
using	Format = Serialization::Format

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.
Serialization::Savable	objectType () const
	Type ID for next object.
Serialization::Format	format () const
	Property: File format.
void	format (Serialization::Format)
	Property: File format.
Progress::Ptr	progress () const
	Property: Progress reporter.
void	progress (const Progress::Ptr &)
	Property: Progress reporter.

Static Public Member Functions
static void	registerSerialization (SerializationRegistration)
static const Sawyer::Optional< SerializationRegistration >	findSerialization (Serialization::Format)
static Serialization::Savable	userSavable (unsigned offset)
	Create a new Savable enum constant.

Static Public Attributes
static Sawyer::Message::Facility	mlog
	Message facility.
static constexpr Format	BINARY = Serialization::BINARY
static constexpr Format	TEXT = Serialization::TEXT
static constexpr Format	XML = Serialization::XML

Protected Member Functions
void	setIsOpen (bool b)
void	objectType (Serialization::Savable)
Serialization::ProgressCallback	makeProgressCB (const std::string &phase)
	Create progress callbacks that wraps the IO progress reporting.

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

Format

using Rose::BinaryAnalysis::SerialIo::Format = Serialization::Format

Definition at line 230 of file SerialIo.h.

Constructor & Destructor Documentation

SerialIo()

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

inlineprotected

Definition at line 124 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 Serialization::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]

Serialization::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

(

Serialization::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::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()

Serialization::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().

makeProgressCB()

Serialization::ProgressCallback Rose::BinaryAnalysis::SerialIo::makeProgressCB ( const std::string &  phase )

protected

Create progress callbacks that wraps the IO progress reporting.

Parameters

phase

The name of the phase for progress reporting

Returns

A callback function that reports progress

Member Data Documentation

progressBar_

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

protected

Definition at line 120 of file SerialIo.h.

fd_

int Rose::BinaryAnalysis::SerialIo::fd_

protected

Definition at line 121 of file SerialIo.h.

mlog

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

static

Message facility.

Definition at line 133 of file SerialIo.h.

BINARY

constexpr Format Rose::BinaryAnalysis::SerialIo::BINARY = Serialization::BINARY

staticconstexpr

Definition at line 231 of file SerialIo.h.

TEXT

constexpr Format Rose::BinaryAnalysis::SerialIo::TEXT = Serialization::TEXT

staticconstexpr

Definition at line 232 of file SerialIo.h.

XML

constexpr Format Rose::BinaryAnalysis::SerialIo::XML = Serialization::XML

staticconstexpr

Definition at line 233 of file SerialIo.h.

---

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

• SerialIo.h