Struct gpiocdev::request::Builder

pub struct Builder { /* private fields */ }

A builder of line requests.

Apply mutators to specify the request configuration, then use request to request the lines from the kernel.

Most mutators operate on the request configuration as per the Config.

Examples

Request and read a basic input line:

let l3 = Request::builder()
    .on_chip("/dev/gpiochip0")
    .with_line(3)
    .request()?;
let value = l3.value(3)?;

Several lines in one request:

let offsets = &[3,5];
let req = Request::builder()
    .on_chip("/dev/gpiochip0")
    .with_lines(offsets)
    .request()?;
let mut values = Values::from_offsets(offsets);
req.values(&mut values)?;

More complex configurations can be built separately and provided to the Builder:

let mut cfg = Config::default();
cfg.with_line(5).as_output(Value::Active);
let req = Request::from_config(cfg)
    .on_chip("/dev/gpiochip0")
    .request()?;
req.set_value(5,Value::Inactive)?;

Implementations

impl Builder

pub fn request(&self) -> Result<Request>

Perform the request.

Sends the request to the kernel using the appropriate uAPI call.

On success returns the Request that provides access to the requested lines.

This is the terminal operation for the Builder.

pub fn with_config(&mut self, cfg: Config) -> &mut Self

Replace the request configuration with the new one provided.

pub fn config(&self) -> Config

Get a snapshot of the current request configuration.

Can be applied to other requests with with_config or Request::from_config.

pub fn with_consumer<N: Into<String>>(&mut self, consumer: N) -> &mut Self

Specify the consumer label to be applied to the request, and so to all lines in the request.

If not specified, a label “gpiocdev-pPID” is applied by request, where PID is the process id of the application.

Examples

let req = Request::builder()
    .on_chip("/dev/gpiochip0")
    .with_lines(&[3,5])
    .with_consumer("spice_weasel")
    .request()?;

pub fn with_kernel_event_buffer_size(
    &mut self,
    event_buffer_size: u32
) -> &mut Self

Set the event buffer size for edge events buffered in the kernel.

This method is only required in unusual circumstances.

The size provides a hint to the kernel as to the size of the buffer to store edge events until they are read from the Request. The default size is 16 times the number of lines in the request. The default size is typically sufficient unless the hardware may generate bursts of events faster than the application can service them.

Altering the buffer size does NOT affect latency. Buffering is provided in the kernel to reduce the likelihood of event loss when user space is slow servicing events. In all cases the events are provided to user space as quickly as user space allows.

pub fn with_user_event_buffer_size(
    &mut self,
    event_buffer_size: usize
) -> &mut Self

Set the event buffer size for edge events buffered in user space.

This method is only required in unusual circumstances.

The size defines the number of events that may be buffered in user space by the Request.edge_events iterator. The user space buffer is a performance optimisation to reduce the number of system calls required to read events.

Altering the buffer size does NOT affect latency. In all cases the events are provided to user space as quickly as user space allows.

pub fn on_chip<P: Into<PathBuf>>(&mut self, path: P) -> &mut Self

Set the chip from which to request lines.

This applies to all lines in the request. It is not possible to request lines from different chips in the same request.

The Builder locks to the first chip provided to it, for example by on_chip or with_found_line. Any subsequent attempts to change the chip will result in an error when request is called.

The chip is identified by a path which must resolve to a GPIO character device.

pub fn as_input(&mut self) -> &mut Self

Set the selected lines to input.

This is a short form of with_direction(Input).

This is the default direction setting.

pub fn as_output(&mut self, value: Value) -> &mut Self

Set the selected lines to output with the given value.

This is a short form of with_direction(Output) and with_value(value) that allows the direction and value to be set in the one call.

pub fn as_active_low(&mut self) -> &mut Self

Set the selected lines to active low.

pub fn as_active_high(&mut self) -> &mut Self

Set the selected lines to active high.

This is the default active level setting.

pub fn with_bias<B: Into<Option<Bias>>>(&mut self, bias: B) -> &mut Self

Set the bias setting for the selected lines.

pub fn with_debounce_period(&mut self, period: Duration) -> &mut Self

Set the debounce period for the selected lines.

A value of zero means no debounce.

Implicitly sets the selected lines as inputs, if they weren’t already, and removes any output specific settings.

pub fn with_direction(&mut self, direction: Direction) -> &mut Self

Set the direction of the selected lines.

Setting to input removes any output specific settings.

Setting to output removes any input specific settings.

pub fn with_drive(&mut self, drive: Drive) -> &mut Self

Set the drive setting for the selected lines.

Implicitly sets the selected lines as outputs, if they weren’t already, and removes any input specific settings.

pub fn with_edge_detection<E: Into<Option<EdgeDetection>>>(
    &mut self,
    edge: E
) -> &mut Self

Set the edge detection for the selected lines.

Implicitly sets the lines as inputs and removes any output specific settings.

pub fn with_event_clock(&mut self, event_clock: EventClock) -> &mut Self

Set the clock source for edge events on the selected lines.

pub fn with_found_line(&mut self, line: &FoundLine) -> &mut Self

Add a found line to the request.

The line must be on the same chip as any existing lines in the request, else the line is ignored and an error returned when request is called.

Note that all configuration mutators applied subsequently only apply to this line.

Examples

let led0 = gpiocdev::find_named_line("LED0").unwrap();
let req = Request::builder()
    .with_found_line(&led0)
    .as_output(Value::Active)
    .request()?;

pub fn with_found_lines<'a>(
    &mut self,
    lines: &HashMap<&'a str, FoundLine>
) -> &mut Self

Add a set of found lines to the request.

The lines must be on the same chip as any existing lines in the request, else the line is ignored and an error returned when request is called.

Note that all configuration mutators applied subsequently only apply to these lines.

Examples

let buttons = gpiocdev::find_named_lines(&["BUTTON0","BUTTON1"], true)?;
let req = Request::builder()
    .with_found_lines(&buttons)
    .with_edge_detection(EdgeDetection::BothEdges)
    .request()?;

pub fn with_line(&mut self, offset: Offset) -> &mut Self

Add a line to the request.

Note that all configuration mutators applied subsequently only apply to this line.

pub fn without_line(&mut self, offset: Offset) -> &mut Self

Remove a lines from the request.

pub fn with_lines(&mut self, offsets: &[Offset]) -> &mut Self

Add a set of lines to the request.

Note that all configuration mutators applied subsequently only apply to this subset of lines.

pub fn without_lines(&mut self, offsets: &[Offset]) -> &mut Self

Remove a set of lines from the request.

pub fn with_value(&mut self, value: Value) -> &mut Self

Set the value of the selected lines.

pub fn from_line_config(&mut self, cfg: &Config) -> &mut Self

Apply the configuration based on a snapshot from a single line.

Trait Implementations

impl Clone for Builder

fn clone(&self) -> Builder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for Builder

fn default() -> Builder

Returns the “default value” for a type.

impl PartialEq<Builder> for Builder

fn eq(&self, other: &Builder) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Builder

impl StructuralEq for Builder

impl StructuralPartialEq for Builder