Tide 0.1.0
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes

tide::Cluster Class Reference

The base Cluster, defining the common interface for Cluster element implementations. More...

#include <tide/cluster.h>

Inheritance diagram for tide::Cluster:
Inheritance graph
[legend]
Collaboration diagram for tide::Cluster:
Collaboration graph
[legend]

List of all members.

Public Types

typedef boost::shared_ptr
< Cluster
Ptr
 Pointer to a cluster.
typedef BlockElement::Ptr value_type
 The value type of this container.
typedef size_t size_type
 The size type of this container.
typedef value_typereference
 The reference type.
typedef value_type const & const_reference
 The constant reference type.

Public Member Functions

 Cluster (uint64_t timecode=0)
 Construct a new Cluster.
virtual ~Cluster ()
 Destructor.
virtual bool empty () const =0
 Check if there are no blocks.
virtual size_type count () const =0
 Get the number of blocks.
virtual void clear ()=0
 Remove all blocks.
virtual void push_back (value_type const &value)=0
 Erase the block at the specified iterator.
uint64_t timecode () const
 Get the cluster's timecode.
void timecode (uint64_t timecode)
 Set the cluster's timecode.
std::vector< SilentTrackNumber > & silent_tracks ()
 Get the list of silent tracks.
uint64_t position () const
 Get the position of this cluster in the segment.
uint64_t previous_size () const
 Get the size of the previous cluster in the segment.
void previous_size (uint64_t size)
 Set the size of the previous cluster in the segment.
std::streamsize size () const
 Get the total size of the element.
std::streamsize read (std::istream &input)
 Element reading.
virtual std::streamsize finalise (std::ostream &output)=0
 Finalise writing of the cluster.

Protected Member Functions

std::streamsize meta_size () const
 Get the size of the meta-data portion of the body of.
std::streamsize body_size () const
 Get the size of the body of this element.
std::streamsize write_size (std::ostream &output)
 Element size writing.
std::streamsize write_body (std::ostream &output)
 Element body writing.
std::streamsize read_body (std::istream &input, std::streamsize size)
 Element body loading.
virtual std::streamsize blocks_size () const =0
 Get the size of the blocks in this cluster.
virtual std::streamsize read_blocks (std::istream &input, std::streamsize size)=0
 Read the blocks in this cluster from the output stream.
std::streamsize read_silent_tracks (std::istream &input)
 Read the SilentTracks child element.
virtual void reset ()
 Reset the cluster's members to default values.

Protected Attributes

UIntElement timecode_
std::vector< SilentTrackNumbersilent_tracks_
UIntElement position_
UIntElement prev_size_
std::streamsize size_
 The size of the cluster.
bool writing_

Detailed Description

The base Cluster, defining the common interface for Cluster element implementations.

This class is the base class for all Cluster implementations. Different concrete implementations of this interface implement reading and writing of blocks in different ways. The two most commonly-used implementations are the in-memory cluster and the streamed-writing cluster.

Because of their nature as streamed data, Clusters are the most complex element to write. They are often written in stages, with a dummy size value and the other data written first, before the blocks are streamed in, and finally the correct size value written over the dummy size value at the start of the cluster. Alternative implementations may store all cluster data in memory (or even in another file) before writing the cluster in one hit.

The Cluster interface supports both streaming and all-at-once approaches to writing. The sequence of method calls is the same for both cases, but what is done for each call varies. The sequence of method calls that must be performed is:

     *  cluster.write(output)
     *          ||
     *          \/
     *  [Capture blocks]
     *          ||
     *          \/
     *  cluster.finalise(output)
     * 

The purpose of the write step is to allow Cluster implementations that use stream-based writing to prepare the file for writing the blocks. The finalise step is used to finalise the cluster in the file, ensuring, for example, that the correct size value is written into the element header.

For a Cluster implementation that stores the block data elsewhere (e.g. in memory) before writing the entire cluster in one go, the method calls could be implemented to do the following:

     *  cluster.write(output)    -> Prepare space outside of the file to store
     *          ||                  the blocks while they are accumulated. For
     *          ||                  example, a block of memory could be
     *          ||                  allocated to store the blocks.
     *          \/
     *  [Capture blocks]         -> Store blocks in the reserved space.
     *          ||
     *          \/
     *  cluster.finalise(output) -> Write the Cluster ID and size (calculated
     *                              from the stored blocks), followed by the
     *                              other Cluster fields, and then the stored
     *                              blocks.
     * 

For a Cluster implementation that streams the blocks directly into the file as they arrive, the method calls could be implemented to do the following:

     *  cluster.write(output)    -> Write the Cluster ID with a base value for
     *          ||                  the size (a good value to use is the size
     *          ||                  of an empty cluster).  Following this,
     *          ||                  write the other Cluster fields.
     *          \/
     *  [Capture blocks]         -> Write blocks directly to the file as they
     *          ||                  are received.
     *          \/
     *  cluster.finalise(output) -> Calculate the actual cluster size (e.g.
     *                              subtract the position in the file of the
     *                              first block from the position in the file
     *                              after the last block), and write it over
     *                              the dummy value written earlier.
     * 

The second approach described above has a very important limitation: no other writes to the file can occur while a cluster is open. To support this restriction, the Cluster interface requires that no writes are performed to the file while a cluster is open. This applies to any implementation, including in-memory implementations, in order to support interchangeability.

Definition at line 139 of file cluster.h.


Member Typedef Documentation

The constant reference type.

Definition at line 151 of file cluster.h.

typedef boost::shared_ptr<Cluster> tide::Cluster::Ptr

Pointer to a cluster.

Definition at line 143 of file cluster.h.

The reference type.

Definition at line 149 of file cluster.h.

typedef size_t tide::Cluster::size_type

The size type of this container.

Definition at line 147 of file cluster.h.

The value type of this container.

Definition at line 145 of file cluster.h.


Constructor & Destructor Documentation

tide::Cluster::Cluster ( uint64_t  timecode = 0)

Construct a new Cluster.

Parameters:
[in]timecodeThe timecode of the cluster, in the units specified by TimecodeScale.
virtual tide::Cluster::~Cluster ( ) [inline, virtual]

Destructor.

Definition at line 161 of file cluster.h.


Member Function Documentation

virtual std::streamsize tide::Cluster::blocks_size ( ) const [protected, pure virtual]

Get the size of the blocks in this cluster.

Implemented in tide::MemoryCluster.

std::streamsize tide::Cluster::body_size ( ) const [inline, protected, virtual]

Get the size of the body of this element.

Implements tide::Element.

Definition at line 280 of file cluster.h.

virtual void tide::Cluster::clear ( ) [pure virtual]

Remove all blocks.

Implemented in tide::MemoryCluster.

virtual size_type tide::Cluster::count ( ) const [pure virtual]

Get the number of blocks.

Implemented in tide::MemoryCluster.

virtual bool tide::Cluster::empty ( ) const [pure virtual]

Check if there are no blocks.

Implemented in tide::MemoryCluster.

virtual std::streamsize tide::Cluster::finalise ( std::ostream &  output) [pure virtual]

Finalise writing of the cluster.

See the Cluster documentation for more details of how this method should be implemented. Once this is called, the cluster should be considered final in the stream, including all the cluster's meta-data and all blocks.

Parameters:
[in]outputThe byte stream to write the cluster to.
Returns:
The final total size, in bytes, of the cluster.

Implemented in tide::MemoryCluster.

std::streamsize tide::Cluster::meta_size ( ) const [protected]

Get the size of the meta-data portion of the body of.

uint64_t tide::Cluster::position ( ) const

Get the position of this cluster in the segment.

This property gives the byte-offset of this cluster in its segment. This value is useful for re-synchronising damaged streams.

If it is zero, then the cluster has not been written or was not read from a byte stream.

uint64_t tide::Cluster::previous_size ( ) const [inline]

Get the size of the previous cluster in the segment.

This property gives the size of the previous cluster in bytes. This can be used to jump straight to the start of the previous cluster, rather than searching for it.

It it is zero, the size of the previous cluster is unknown.

Definition at line 237 of file cluster.h.

void tide::Cluster::previous_size ( uint64_t  size) [inline]

Set the size of the previous cluster in the segment.

Definition at line 239 of file cluster.h.

virtual void tide::Cluster::push_back ( value_type const &  value) [pure virtual]

Erase the block at the specified iterator.

Parameters:
[in]positionThe position to erase at.Erase a range of blocks.
[in]firstThe start of the range.
[in]lastThe end of the range.Add a block to this cluster.

The cluster must be in the writable state. This means that write() has been called and finish_write() has not been called.

Exceptions:
ClusterNotReadyif the Cluster is not in the correct state for writing blocks.

Implemented in tide::MemoryCluster.

std::streamsize tide::Cluster::read ( std::istream &  input) [inline, virtual]

Element reading.

Exceptions:
DuplicateTrackNumberif more than one TrackEntry in the stored element has the same track number.
DuplicateUIDif more than one TrackEntry in the stored element has the same UID.

Reimplemented from tide::Element.

Definition at line 251 of file cluster.h.

virtual std::streamsize tide::Cluster::read_blocks ( std::istream &  input,
std::streamsize  size 
) [protected, pure virtual]

Read the blocks in this cluster from the output stream.

This function may not necessarily perform the actual reading, but once called, the blocks should be accessible through whatever interface the Cluster implementation provides.

For example, if the blocks are actually read by an iterator, calling this function should prepare for the iterators' use. It might, for example, read the position of each block and store it in an index.

Parameters:
[in]inputThe input byte stream to read blocks from.
[in]sizeThe number of bytes available for reading. Exactly this many bytes should be used, or an error should be reported.
Returns:
The total size of the cluster's blocks (as stored in the stream), i.e. the quantity of data "read". Even if only a small quantity of data is actually read, it must return the complete blocks size of the cluster in order to meet the Element interface requirements.

Implemented in tide::MemoryCluster.

std::streamsize tide::Cluster::read_body ( std::istream &  input,
std::streamsize  size 
) [protected, virtual]

Element body loading.

Implements tide::Element.

std::streamsize tide::Cluster::read_silent_tracks ( std::istream &  input) [protected]

Read the SilentTracks child element.

Returns:
The number of bytes read.
virtual void tide::Cluster::reset ( ) [protected, virtual]

Reset the cluster's members to default values.

std::vector<SilentTrackNumber>& tide::Cluster::silent_tracks ( ) [inline]

Get the list of silent tracks.

Some tracks in a cluster may be marked as silent. This means that all blocks for those tracks should be ignored within this cluster. This property lists the track numbers of the silent tracks.

A track being made silent in this cluster has no effect on its silence in other clusters.

Definition at line 216 of file cluster.h.

std::streamsize tide::Cluster::size ( ) const [virtual]

Get the total size of the element.

Reimplemented from tide::Element.

void tide::Cluster::timecode ( uint64_t  timecode) [inline]

Set the cluster's timecode.

Definition at line 204 of file cluster.h.

uint64_t tide::Cluster::timecode ( ) const [inline]

Get the cluster's timecode.

This timecode defines the base timecode for all blocks in the cluster. It is specified in units of the TimecodeScale found in the SegmentInfo element for the same segment as the cluster.

Definition at line 202 of file cluster.h.

std::streamsize tide::Cluster::write_body ( std::ostream &  output) [protected, virtual]

Element body writing.

Implements tide::Element.

std::streamsize tide::Cluster::write_size ( std::ostream &  output) [protected, virtual]

Element size writing.

Reimplemented from tide::Element.


Member Data Documentation

Definition at line 269 of file cluster.h.

Definition at line 270 of file cluster.h.

Definition at line 268 of file cluster.h.

std::streamsize tide::Cluster::size_ [protected]

The size of the cluster.

Definition at line 272 of file cluster.h.

Definition at line 267 of file cluster.h.

bool tide::Cluster::writing_ [protected]

Definition at line 273 of file cluster.h.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines