Module parse 

Parsing interface for parsing data in to record types.

In this crate, parsing is built on parser functions that take in a Parser and produce a Result<T> where T is some record type. Most of the time, you should be able to call Parser::parse for each of your fields but Parser provides many other helper methods for when that isn’t enough.

Parsing a Record

The quickest and easiest way to get started is to just parse everything to the Record type.

use perf_event_data::endian::Little;
use perf_event_data::parse::{ParseConfig, Parser};
use perf_event_data::Record;

let data: &[u8] = // ...
let config = ParseConfig::<Little>::default();
let mut parser = Parser::new(data, config);
let record: Record = parser.parse()?;

Parsing Custom Types

The types provided in this crate aim to cover all the possible types of record that can be emitted by perf_event_open. However, if you control the configuration passed to perf_event_open then the types in this crate can be overly general. You may find it easier to define custom types that match exactly the record types you know will be generated.

To do that you will need to implement Parse for your type, use Parser::parse_metadata to parse the record frame, and then use Parser::parse to parse your custom record type.

Here we define a sample type that only parses the custom fields we care about.

use perf_event_data::endian::{Endian, Little};
use perf_event_data::parse::{Parse, ParseBuf, ParseConfig, ParseResult, Parser};
use perf_event_data::Registers;
use perf_event_open_sys::bindings::PERF_RECORD_SAMPLE;

struct CustomSample {
    pub ip: u64,
    pub pid: u32,
    pub tid: u32,
    pub callstack: Vec<u64>,
    pub cgroup: u64,
}

impl<'p> Parse<'p> for CustomSample {
    fn parse<B, E>(p: &mut Parser<B, E>) -> ParseResult<Self>
    where
        B: ParseBuf<'p>,
        E: Endian,
    {
        Ok(Self {
            ip: p.parse()?,
            pid: p.parse()?,
            tid: p.parse()?,
            callstack: {
                let len = p.parse_u64()?;
                p.parse_repeated(len as usize)?
            },
            cgroup: p.parse()?,
        })
    }
}

let data: &[u8] = // ...
let attr: perf_event_open_sys::bindings::perf_event_attr = // ...
let config: ParseConfig<Little> = ParseConfig::from(attr);
let mut parser = Parser::new(data, config);

let (mut p, metadata) = parser.parse_metadata()?;

assert_eq!(metadata.ty(), PERF_RECORD_SAMPLE);
let sample: CustomSample = p.parse()?;

Structs

ParseConfig

All the configuration data needed to parse any perf record.

ParseError

The error type for parsing errors as returned by Parser.

Parser

A ParseConfig combined with a ParseBuf.

Enums

ErrorKind

A list specifying general categories of parse error.

ParseBufChunk

A continuous chunk of data read from a ParseBuf.

Traits

Parse

A type that can be parsed

ParseBuf

A data source from which Parser can parse data.

Type Aliases

ParseResult

A specialized result type used by Parse and Parser.