Struct Parser

pub struct Parser<B, E> { /* private fields */ }

A ParseConfig combined with a ParseBuf.

This type is the base on which all parsing in this library occurs. It has a number of helper methods that do common parsing operations needed when implementing Parse for a record type.

Important Methods

If you are using this library to parse an perf event stream emitted either by perf_event_open(2) or by parsing a perf.data file then likely want one of

• parse_record, or,
• parse_record_with_header

If you are implementing Parse for a type then you will likely be using

• parse, and,
• parse_bytes

Other methods are provided if they were needed but those should be the main ones.

Implementations

impl<'p, B, E> Parser<B, E>

where E: Endian, B: ParseBuf<'p>,

pub fn new(data: B, config: ParseConfig<E>) -> Self

Create a new parser.

pub fn config(&self) -> &ParseConfig<E>

Get the ParseConfig instance for this Parser.

pub fn endian(&self) -> &E

Get the endian configuration type.

pub fn parse_bytes(&mut self, len: usize) -> ParseResult<Cow<'p, [u8]>>

Directly get a reference to the next len bytes in the input buffer.

pub fn parse<P: Parse<'p>>(&mut self) -> ParseResult<P>

Parse a type.

If the type fails to parse then this parser will not be modified.

pub fn parse_with<F, R>(&mut self, func: F) -> ParseResult<R>

where F: FnOnce(&mut Self) -> ParseResult<R>,

Parse with an explicit parsing function.

pub fn parse_if<P: Parse<'p>>(&mut self, parse: bool) -> ParseResult<Option<P>>

Parse a type only if parse is true.

pub fn parse_if_with<F, R>( &mut self, parse: bool, func: F, ) -> ParseResult<Option<R>>

where F: FnOnce(&mut Self) -> ParseResult<R>,

parse_if but using an explicit parsing function.

pub fn parse_u8(&mut self) -> ParseResult<u8>

Parse a single byte out of the source buffer.

pub fn parse_u16(&mut self) -> ParseResult<u16>

Parse a u16 out of the source data.

pub fn parse_u32(&mut self) -> ParseResult<u32>

Parse a u32 out of the source data.

pub fn parse_u64(&mut self) -> ParseResult<u64>

Parse a u64 out of the source data.

pub fn parse_rest(&mut self) -> ParseResult<Cow<'p, [u8]>>

Consume the rest of the buffer and return it as a slice.

pub fn parse_rest_trim_nul(&mut self) -> ParseResult<Cow<'p, [u8]>>

Parse the rest of the bytes in the buffer but trim trailing nul bytes.

pub unsafe fn parse_slice_direct<T>( &mut self, len: usize, ) -> ParseResult<Option<&'p [T]>>

where T: Copy,

Attempt to directly transmute a slice in the source buffer to one of type T.

This method will only succeed if

1. the source endianness is the same as the endianness of this program, and
2. the buffer is properly aligned for T.

This method is mainly meant to reduce copying when parsing the records emitted directly from the kernel. If you are parsing from a buffer read in from a file then it is unlikely that you will meet all the required preconditions.

Safety

It must be valid to transmute T directly from bytes. The Copy bound is a step towards ensuring this.

pub unsafe fn parse_slice<T>(&mut self, len: usize) -> ParseResult<Cow<'p, [T]>>

where T: Parse<'p> + Copy,

Attempt to directly transmute a slice in the source buffer and, if that fails, parse it instead.

Safety

This has all the same safety preconditions as parse_slice_direct. That is, is must be valid to transmute bytes in to a T instance.

pub fn parse_repeated<T: Parse<'p>>( &mut self, len: usize, ) -> ParseResult<Vec<T>>

Parse a sequence of len Ts.

pub fn parse_metadata( &mut self, ) -> ParseResult<(Parser<impl ParseBuf<'p>, E>, RecordMetadata)>

Parse record metadata and return a parser for the bytes of the record.

If you have already read the record header, use parse_metadata_with_header instead.

pub fn parse_metadata_with_header( &mut self, header: perf_event_header, ) -> ParseResult<(Parser<impl ParseBuf<'p>, E>, RecordMetadata)>

Parse the record metadata and return a parser for only the record bytes.

pub fn parse_record<V: Visitor<'p>>( &mut self, visitor: V, ) -> ParseResult<V::Output>

Parse a record, the record types will be visited by the visitor.

pub fn parse_record_with_header<V: Visitor<'p>>( &mut self, visitor: V, header: perf_event_header, ) -> ParseResult<V::Output>

Same as parse_record but required that the header be provided.

Trait Implementations

impl<B: Clone, E: Clone> Clone for Parser<B, E>

fn clone(&self) -> Parser<B, E>

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.