Tawara  0.1.0
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
tawara::Cluster Class Referenceabstract

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

#include <tawara/cluster.h>

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

Public Types

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

Public Member Functions

 Cluster (uint64_t timecode=0)
 Construct a new Cluster. More...
 
virtual ~Cluster ()
 Destructor. More...
 
virtual bool empty () const =0
 Check if there are no blocks. More...
 
virtual size_type count () const =0
 Get the number of blocks. More...
 
virtual void clear ()=0
 Remove all blocks. More...
 
virtual void push_back (value_type const &value)=0
 Add a block to this cluster. More...
 
uint64_t timecode () const
 Get the cluster's timecode. More...
 
void timecode (uint64_t timecode)
 Set the cluster's timecode. More...
 
std::vector< SilentTrackNumber > & silent_tracks ()
 Get the list of silent tracks. More...
 
uint64_t position () const
 Get the position of this cluster in the segment. More...
 
uint64_t previous_size () const
 Get the size of the previous cluster in the segment. More...
 
void previous_size (uint64_t size)
 Set the size of the previous cluster in the segment. More...
 
std::streamsize size () const
 Get the total size of the element. More...
 
std::streamsize read (std::istream &input)
 Element reading. More...
 
virtual std::streamsize finalise (std::ostream &output)=0
 Finalise writing of the cluster. More...
 
- Public Member Functions inherited from tawara::MasterElement
 MasterElement (uint32_t id, bool crc=false)
 Create a new MasterElement. More...
 
virtual ~MasterElement ()
 Destructor. More...
 
- Public Member Functions inherited from tawara::Element
 Element (tawara::ids::ID id)
 Create a new Element. More...
 
virtual ~Element ()
 Destructor. More...
 
uint32_t id () const
 Get the element's ID. More...
 
std::streampos offset () const
 Get the element's offset in the byte stream. More...
 
virtual std::streamsize write (std::ostream &output)
 Element writing. More...
 

Protected Member Functions

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

Protected Attributes

UIntElement timecode_
 
std::vector< SilentTrackNumbersilent_tracks_
 
UIntElement position_
 
UIntElement prev_size_
 
bool writing_
 
- Protected Attributes inherited from tawara::Element
tawara::ids::ID id_
 
std::streampos offset_
 

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: the cluster implementation must manage the file write pointer carefully to ensure that blocks are placed in the correct place in the file. For example, upon receiving a block to write, the file write pointer is positioned after the previously-written block, and after writing the block is returned to the position it was originally in.

Definition at line 150 of file cluster.h.

Member Typedef Documentation

The constant reference type.

Definition at line 162 of file cluster.h.

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

Pointer to a cluster.

Definition at line 154 of file cluster.h.

The reference type.

Definition at line 160 of file cluster.h.

The size type of this container.

Definition at line 158 of file cluster.h.

The value type of this container.

Definition at line 156 of file cluster.h.

Constructor & Destructor Documentation

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

Construct a new Cluster.

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

Destructor.

Definition at line 172 of file cluster.h.

Member Function Documentation

virtual std::streamsize tawara::Cluster::blocks_size ( ) const
protectedpure virtual

Get the size of the blocks in this cluster.

Implemented in tawara::FileCluster, and tawara::MemoryCluster.

std::streamsize tawara::Cluster::body_size ( ) const
inlineprotectedvirtual

Get the size of the body of this element.

Implements tawara::Element.

Definition at line 290 of file cluster.h.

virtual void tawara::Cluster::clear ( )
pure virtual

Remove all blocks.

Implemented in tawara::FileCluster, and tawara::MemoryCluster.

virtual size_type tawara::Cluster::count ( ) const
pure virtual

Get the number of blocks.

Implemented in tawara::FileCluster, and tawara::MemoryCluster.

virtual bool tawara::Cluster::empty ( ) const
pure virtual

Check if there are no blocks.

Implemented in tawara::FileCluster, and tawara::MemoryCluster.

virtual std::streamsize tawara::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 tawara::FileCluster, and tawara::MemoryCluster.

std::streamsize tawara::Cluster::meta_size ( ) const
protected

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

uint64_t tawara::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 tawara::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 249 of file cluster.h.

void tawara::Cluster::previous_size ( uint64_t  size)
inline

Set the size of the previous cluster in the segment.

Definition at line 251 of file cluster.h.

virtual void tawara::Cluster::push_back ( value_type const &  value)
pure virtual

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 tawara::FileCluster, and tawara::MemoryCluster.

std::streamsize tawara::Cluster::read ( std::istream &  input)
inlinevirtual

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 tawara::Element.

Definition at line 263 of file cluster.h.

virtual std::streamsize tawara::Cluster::read_blocks ( std::istream &  input,
std::streamsize  size 
)
protectedpure 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 tawara::FileCluster, and tawara::MemoryCluster.

std::streamsize tawara::Cluster::read_body ( std::istream &  input,
std::streamsize  size 
)
protectedvirtual

Element body loading.

Implements tawara::Element.

std::streamsize tawara::Cluster::read_silent_tracks ( std::istream &  input)
protected

Read the SilentTracks child element.

Returns
The number of bytes read.
virtual void tawara::Cluster::reset ( )
protectedvirtual

Reset the cluster's members to default values.

std::vector<SilentTrackNumber>& tawara::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 228 of file cluster.h.

std::streamsize tawara::Cluster::size ( ) const
virtual

Get the total size of the element.

Reimplemented from tawara::Element.

uint64_t tawara::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 214 of file cluster.h.

void tawara::Cluster::timecode ( uint64_t  timecode)
inline

Set the cluster's timecode.

Definition at line 216 of file cluster.h.

std::streamsize tawara::Cluster::write_body ( std::ostream &  output)
protectedvirtual

Element body writing.

Implements tawara::Element.

std::streamsize tawara::Cluster::write_size ( std::ostream &  output)
protectedvirtual

Element size writing.

Reimplemented from tawara::Element.

Member Data Documentation

UIntElement tawara::Cluster::position_
protected

Definition at line 281 of file cluster.h.

UIntElement tawara::Cluster::prev_size_
protected

Definition at line 282 of file cluster.h.

std::vector<SilentTrackNumber> tawara::Cluster::silent_tracks_
protected

Definition at line 280 of file cluster.h.

UIntElement tawara::Cluster::timecode_
protected

Definition at line 279 of file cluster.h.

bool tawara::Cluster::writing_
protected

Definition at line 283 of file cluster.h.


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