Struct Writer

pub struct Writer<W: Write + Seek> { /* private fields */ }

Writes an MCAP file to the given writer.

Users should call finish() to flush the stream and check for errors when done; otherwise the result will be unwrapped on drop.

Implementations

impl<W: Write + Seek> Writer<W>

pub fn new(writer: W) -> McapResult<Self>

Create a new MCAP Writer using the provided seeking writer.

pub fn with_options(writer: W, opts: WriteOptions) -> McapResult<Self>

Create a new MCAP Writer using the provided seeking writer and WriteOptions.

pub fn add_schema( &mut self, name: &str, encoding: &str, data: &[u8], ) -> McapResult<u16>

Adds a schema, returning its ID. If a schema with the same content has been added already, its ID is returned.

• name: an identifier for the schema.
• encoding: Describes the schema format. The well-known schema encodings are preferred. An empty string indicates no schema is available.
• data: The serialized schema content. If encoding is an empty string, data should have zero length.

pub fn add_channel( &mut self, schema_id: u16, topic: &str, message_encoding: &str, metadata: &BTreeMap<String, String>, ) -> McapResult<u16>

Adds a channel, returning its ID. If a channel with equivalent content was added previously, its ID is returned.

Useful with subsequent calls to write_to_known_channel().

• schema_id: a schema_id returned from Self::add_schema, or 0 if the channel has no schema.
• topic: The topic name.
• message_encoding: Encoding for messages on this channel. The well-known message encodings are preferred.
• metadata: Metadata about this channel.

pub fn write(&mut self, message: &Message<'_>) -> McapResult<()>

Write the given message (and its provided channel, if not already added). The provided channel ID and schema ID will be used as IDs in the resulting MCAP.

pub fn write_to_known_channel( &mut self, header: &MessageHeader, data: &[u8], ) -> McapResult<()>

Write a message to an added channel, given its ID.

This skips hash lookups of the channel and schema if you already added them.

pub fn write_private_record( &mut self, opcode: u8, data: &[u8], options: EnumSet<PrivateRecordOptions>, ) -> McapResult<()>

Write a private record using the provided options.

Private records must have an opcode >= 0x80.

pub fn start_attachment( &mut self, attachment_length: u64, header: AttachmentHeader, ) -> McapResult<()>

Start writing an attachment.

This is a low level API. For small attachments, use Self::attach.

To start writing an attachment call this method with the AttachmentHeader as well as the length of the attachment in bytes. It is important this length is exact otherwise the writer will be left in an error state.

This call should be followed by one or more calls to Self::put_attachment_bytes.

Once all attachment bytes have been written the attachment must be completed with a call to Self::finish_attachment. Failing to finish the attachment will leave the write in an error state.

Example

let attachment_length = 6;

// Start the attachment
writer.start_attachment(attachment_length, AttachmentHeader {
    log_time: 100,
    create_time: 200,
    name: "my-attachment".into(),
    media_type: "application/octet-stream".into()
})?;

// Write all the bytes for the attachment. The amount of bytes written must
// match the length specified when the attachment was started.
writer.put_attachment_bytes(&[ 1, 2, 3, 4 ])?;
writer.put_attachment_bytes(&[ 5, 6 ])?;

// Finish writing the attachment.
writer.finish_attachment()?;

pub fn put_attachment_bytes(&mut self, bytes: &[u8]) -> McapResult<()>

Write bytes to the current attachment.

This is a low level API. For small attachments, use Self::attach.

Before calling this method call Self::start_attachment.

pub fn finish_attachment(&mut self) -> McapResult<()>

Finish the current attachment.

This is a low level API. For small attachments, use Self::attach.

Before calling this method call Self::start_attachment and write bytes to the attachment using Self::put_attachment_bytes.

pub fn attach(&mut self, attachment: &Attachment<'_>) -> McapResult<()>

Write an attachment to the MCAP file. This finishes any current chunk before writing the attachment.

pub fn write_metadata(&mut self, metadata: &Metadata) -> McapResult<()>

Write a Metadata record to the MCAP file. This finishes any current chunk before writing the metadata.

pub fn flush(&mut self) -> McapResult<()>

Finishes the current chunk, if we have one, and flushes the underlying writer.

We finish the chunk to guarantee that the file can be streamed by future readers at least up to this point. (The alternative is to just flush the writer mid-chunk. But if we did that, and then writing was suddenly interrupted afterwards, readers would have to try to recover a half-written chunk, probably with an unfinished compression stream.)

Note that lossless compression schemes like LZ4 and Zstd improve as they go, so larger chunks will tend to have better compression. (Of course, this depends heavily on the entropy of what’s being compressed! A stream of zeroes will compress great at any chunk size, and a stream of random data will compress terribly at any chunk size.)

pub fn finish(&mut self) -> McapResult<Summary>

Finishes any current chunk and writes out the summary section of the file.

Returns a Summary of data written to the file. Subsequent calls to other methods will panic.

pub fn into_inner(self) -> W

Consumes this writer, returning the underlying stream. Unless Self::finish() was called first, the underlying stream will not contain a complete MCAP.

Use this if you wish to handle any errors returned when the underlying stream is closed. In particular, if using std::fs::File, you may wish to call std::fs::File::sync_all() to ensure all data was sent to the filesystem.

Trait Implementations

impl<W: Write + Seek> Drop for Writer<W>

fn drop(&mut self)

Executes the destructor for this type.