Merge #40

40: Prep 0.4.0, Error changes, MSRV Bump r=nastevens a=posborne

* Prep 0.4.0 Release
* Deperecate odd errors module and expose via re-export at top-level (argument could be made to just rip the band-aid off here or to not make the change at all).
* Fix testing to cover async changes and MSRV to be compatible with those (we are doing a major version bump so this is OK) 
* Add some more docs content for the async changes

Co-authored-by: Paul Osborne <[email protected]>

Author: bors[bot]

.travis.yml

@@ -72,7 +72,7 @@ matrix:
 
     # MSRV
     - env: TARGET=x86_64-unknown-linux-gnu
-      rust: 1.38.0
+      rust: 1.39.0
       if: (branch = staging OR branch = trying) OR (type = pull_request AND branch = master)
 
 before_install:

CHANGELOG.md

@@ -8,6 +8,12 @@ Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## v0.4.0 - 2020-08-01
+
+- Removed pub "errors" module.  Error now exposed at top level.
+- MSRV is now 1.39.0
+- Add support behind a feature flag for reading events from a line as a Stream via tokio. [#35](https://github.com/rust-embedded/gpio-cdev/pull/35).
+
 ## v0.3.0 - 2020-02-10
 
 Refactored Errors:

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "gpio-cdev"
-version = "0.3.0"
+version = "0.4.0"
 authors = ["Paul Osborne <[email protected]>", "Frank Pagliughi <[email protected]>"]
 description = "Linux GPIO Character Device Support (/dev/gpiochipN)"
 homepage = "https://github.com/posborne/rust-gpio-cdev"

README.md

@@ -23,9 +23,14 @@ Add the following to your Cargo.toml
 
 ```
 [dependencies]
-gpio-cdev = "0.2"
+gpio-cdev = "0.4"
 ```
 
+Note that the following features are available:
+
+* `async-tokio`: Adds a Stream interface for consuming GPIO events in async code
+  within a tokio runtime.
+
 ## Examples
 
 There are several additional examples available in the [examples
@@ -58,7 +63,7 @@ use gpio_cdev::{Chip, LineRequestFlags, EventRequestFlags, EventType};
 // on gpiochip0 and mirror its state on another line.  With this you
 // could, for instance, control the state of an LED with a button
 // if hooked up to the right pins on a raspberry pi.
-fn mirror_gpio(inputline: u32, outputline: u32) -> gpio_cdev::errors::Result<()> {
+fn mirror_gpio(inputline: u32, outputline: u32) -> Result<(), gpio_cdev::Error> {
     let mut chip = Chip::new("/dev/gpiochip0")?;
     let input = chip.get_line(inputline)?;
     let output = chip.get_line(outputline)?;
@@ -84,6 +89,32 @@ fn mirror_gpio(inputline: u32, outputline: u32) -> gpio_cdev::errors::Result<()>
 }
 ```
 
+### Async Usage
+
+Note that this requires the addition of the `async-tokio` feature.
+
+```rust
+use futures::stream::StreamExt;
+use gpio_cdev::{Chip, AsyncLineEventHandle};
+
+async fn gpiomon(chip: String, line: u32) -> gpio_cdev::Result<()> {
+    let mut chip = Chip::new(args.chip)?;
+    let line = chip.get_line(args.line)?;
+    let mut events = AsyncLineEventHandle::new(line.events(
+        LineRequestFlags::INPUT,
+        EventRequestFlags::BOTH_EDGES,
+        "gpioevents",
+    )?)?;
+
+    while let Some(event) = events.next().await {
+        let event = event?;
+        println!("GPIO Event: {:?}", event);
+    }
+
+    Ok(())
+}
+```
+
 ## Sysfs GPIO vs GPIO Character Device
 
 Compared to the sysfs gpio interface (as made available by the sysfs_gpio crate)
@@ -175,7 +206,7 @@ to be considered reliable.
 
 ## Minimum Supported Rust Version (MSRV)
 
-This crate is guaranteed to compile on stable Rust 1.38.0 and up. It *might*
+This crate is guaranteed to compile on stable Rust 1.39.0 and up. It *might*
 compile with older versions but that may change in any new patch release.
 
 ## License

ci/script.sh

@@ -3,15 +3,15 @@
 set -ex
 
 main() {
-    cross build --target $TARGET
-    cross build --target $TARGET --release
+    cross build --target $TARGET --all-features
+    cross build --target $TARGET --release --all-features
 
     if [ ! -z $DISABLE_TESTS ]; then
         return
     fi
 
-    cross test --target $TARGET
-    cross test --target $TARGET --release
+    cross test --target $TARGET --all-features
+    cross test --target $TARGET --release --all-features
 
     # No main binary, so skip the 'cross run' portion
     # cross run --target $TARGET

examples/async_tokio.rs

@@ -7,7 +7,7 @@
 // except according to those terms.
 
 use futures::stream::StreamExt;
-use gpio_cdev::*;
+use gpio_cdev::{AsyncLineEventHandle, Chip, EventRequestFlags, LineRequestFlags};
 use quicli::prelude::*;
 
 #[derive(Debug, StructOpt)]
@@ -18,7 +18,7 @@ struct Cli {
     line: u32,
 }
 
-async fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
+async fn do_main(args: Cli) -> std::result::Result<(), gpio_cdev::Error> {
     let mut chip = Chip::new(args.chip)?;
     let line = chip.get_line(args.line)?;
     let mut events = AsyncLineEventHandle::new(line.events(

examples/blinky.rs

@@ -6,16 +6,11 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-extern crate gpio_cdev;
-#[macro_use]
-extern crate quicli;
-
-use gpio_cdev::*;
+use gpio_cdev::{Chip, LineRequestFlags};
 use quicli::prelude::*;
 use std::thread::sleep;
 use std::time::{Duration, Instant};
 
-
 #[derive(Debug, StructOpt)]
 struct Cli {
     /// The gpiochip device (e.g. /dev/gpiochip0)
@@ -28,7 +23,7 @@ struct Cli {
     duration_ms: u64,
 }
 
-fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
+fn do_main(args: Cli) -> std::result::Result<(), gpio_cdev::Error> {
     let mut chip = Chip::new(args.chip)?;
 
     // NOTE: we set the default value to the desired state so
@@ -49,7 +44,7 @@ fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
     Ok(())
 }
 
-main!(|args: Cli| match do_main(args) {
+quicli::main!(|args: Cli| match do_main(args) {
     Ok(()) => {}
     Err(e) => {
         println!("Error: {:?}", e);

examples/driveoutput.rs

@@ -6,11 +6,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-extern crate gpio_cdev;
-#[macro_use]
-extern crate quicli;
-
-use gpio_cdev::*;
+use gpio_cdev::{Chip, LineRequestFlags};
 use quicli::prelude::*;
 
 #[derive(Debug, StructOpt)]
@@ -23,7 +19,7 @@ struct Cli {
     value: u8,
 }
 
-fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
+fn do_main(args: Cli) -> std::result::Result<(), gpio_cdev::Error> {
     let mut chip = Chip::new(args.chip)?;
 
     // NOTE: we set the default value to the desired state so
@@ -44,7 +40,7 @@ fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
     Ok(())
 }
 
-main!(|args: Cli| match do_main(args) {
+quicli::main!(|args: Cli| match do_main(args) {
     Ok(()) => {}
     Err(e) => {
         println!("Error: {:?}", e);

examples/gpioevents.rs

@@ -6,14 +6,9 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-extern crate gpio_cdev;
-#[macro_use]
-extern crate quicli;
-
-use gpio_cdev::*;
+use gpio_cdev::{Chip, EventRequestFlags, LineRequestFlags};
 use quicli::prelude::*;
 
-
 #[derive(Debug, StructOpt)]
 struct Cli {
     /// The gpiochip device (e.g. /dev/gpiochip0)
@@ -22,7 +17,7 @@ struct Cli {
     line: u32,
 }
 
-fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
+fn do_main(args: Cli) -> std::result::Result<(), gpio_cdev::Error> {
     let mut chip = Chip::new(args.chip)?;
     let line = chip.get_line(args.line)?;
 
@@ -37,7 +32,7 @@ fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
     Ok(())
 }
 
-main!(|args: Cli| match do_main(args) {
+quicli::main!(|args: Cli| match do_main(args) {
     Ok(()) => {}
     Err(e) => {
         println!("Error: {:?}", e);

examples/multioutput.rs

@@ -6,11 +6,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-extern crate gpio_cdev;
-#[macro_use]
-extern crate quicli;
-
-use gpio_cdev::*;
+use gpio_cdev::{Chip, LineRequestFlags};
 use quicli::prelude::*;
 
 #[derive(Debug, StructOpt)]
@@ -28,7 +24,7 @@ struct Cli {
 // to set lines 0, 1, & 3 high
 //              2 & 4 low
 //
-fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
+fn do_main(args: Cli) -> std::result::Result<(), gpio_cdev::Error> {
     let mut chip = Chip::new(args.chip)?;
     let mut offsets = Vec::new();
     let mut values = Vec::new();
@@ -52,7 +48,7 @@ fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
     Ok(())
 }
 
-main!(|args: Cli| match do_main(args) {
+quicli::main!(|args: Cli| match do_main(args) {
     Ok(()) => {}
     Err(e) => {
         println!("Error: {:?}", e);

examples/multiread.rs

@@ -6,11 +6,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-extern crate gpio_cdev;
-#[macro_use]
-extern crate quicli;
-
-use gpio_cdev::*;
+use gpio_cdev::{Chip, LineRequestFlags};
 use quicli::prelude::*;
 
 #[derive(Debug, StructOpt)]
@@ -21,18 +17,18 @@ struct Cli {
     lines: Vec<u32>,
 }
 
-fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
+fn do_main(args: Cli) -> std::result::Result<(), gpio_cdev::Error> {
     let mut chip = Chip::new(args.chip)?;
-    let ini_vals = vec![ 0; args.lines.len() ];
-    let handle = chip
-        .get_lines(&args.lines)?
-        .request(LineRequestFlags::INPUT, &ini_vals, "multiread")?;
+    let ini_vals = vec![0; args.lines.len()];
+    let handle =
+        chip.get_lines(&args.lines)?
+            .request(LineRequestFlags::INPUT, &ini_vals, "multiread")?;
     println!("Values: {:?}", handle.get_values()?);
 
     Ok(())
 }
 
-main!(|args: Cli| match do_main(args) {
+quicli::main!(|args: Cli| match do_main(args) {
     Ok(()) => {}
     Err(e) => {
         println!("Error: {:?}", e);

examples/readall.rs

@@ -6,11 +6,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-extern crate gpio_cdev;
-#[macro_use]
-extern crate quicli;
-
-use gpio_cdev::*;
+use gpio_cdev::{Chip, LineRequestFlags};
 use quicli::prelude::*;
 
 #[derive(Debug, StructOpt)]
@@ -19,7 +15,7 @@ struct Cli {
     chip: String,
 }
 
-fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
+fn do_main(args: Cli) -> std::result::Result<(), gpio_cdev::Error> {
     let mut chip = Chip::new(args.chip)?;
     let ini_vals = vec![0; chip.num_lines() as usize];
     let handle = chip
@@ -30,7 +26,7 @@ fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
     Ok(())
 }
 
-main!(|args: Cli| match do_main(args) {
+quicli::main!(|args: Cli| match do_main(args) {
     Ok(()) => {}
     Err(e) => {
         println!("Error: {:?}", e);

examples/readinput.rs

@@ -6,11 +6,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-extern crate gpio_cdev;
-#[macro_use]
-extern crate quicli;
-
-use gpio_cdev::*;
+use gpio_cdev::{Chip, LineRequestFlags};
 use quicli::prelude::*;
 
 #[derive(Debug, StructOpt)]
@@ -21,7 +17,7 @@ struct Cli {
     line: u32,
 }
 
-fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
+fn do_main(args: Cli) -> std::result::Result<(), gpio_cdev::Error> {
     let mut chip = Chip::new(args.chip)?;
     let handle = chip
         .get_line(args.line)?
@@ -31,7 +27,7 @@ fn do_main(args: Cli) -> std::result::Result<(), errors::Error> {
     Ok(())
 }
 
-main!(|args: Cli| match do_main(args) {
+quicli::main!(|args: Cli| match do_main(args) {
     Ok(()) => {}
     Err(e) => {
         println!("Error: {:?}", e);