Add callback

.github/workflows/cd-test.yml

@@ -0,0 +1,18 @@
+# Copyright (C) 2023 Nitrokey GmbH
+# SPDX-License-Identifier: CC0-1.0
+
+name: Continuous delivery - test
+
+on:
+  pull_request:
+    # opened, reopenened, synchronize are the default types for pull_request
+    # labeled, unlabeled ensure this check is also run if a label is added or removed
+    types: [opened, reopened, synchronize, labeled, unlabeled]
+
+jobs:
+  test-publish:
+    runs-on: ubuntu-latest
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'skip-publish-check') }}
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+    - run: cargo publish --dry-run

.github/workflows/cd.yml

@@ -0,0 +1,23 @@
+# Copyright (C) 2023 Nitrokey GmbH
+# SPDX-License-Identifier: CC0-1.0
+
+name: Continuous delivery - crates.io
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: crates.io
+    permissions:
+      id-token: write
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+    - uses: rust-lang/crates-io-auth-action@c6f97d42243bad5fab37ca0427f495c86d5b1a18  # v1.0.5
+      id: auth
+    - run: cargo publish
+      env:
+        CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}

CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 -
 
+## [0.3.3][] - 2026-09-15
+
+### Added
+
+- Add callbacks to `Requester` and `Responder` by adding a `callback_mut` function.
+
 ## [0.3.2][] - 2024-01-14
 
 ### Added
@@ -41,7 +47,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Changes API to use references instead of moves.
   This improves stack usage.
 
-[Unreleased]: https://github.com/trussed-dev/interchange/compare/0.3.2...HEAD
+[Unreleased]: https://github.com/trussed-dev/interchange/compare/0.3.3...HEAD
+[0.3.2]: https://github.com/trussed-dev/interchange/compare/0.3.2...0.3.3
 [0.3.2]: https://github.com/trussed-dev/interchange/compare/0.3.1...0.3.2
 [0.3.1]: https://github.com/trussed-dev/interchange/compare/0.3.0...0.3.1
 [0.3.0]: https://github.com/trussed-dev/interchange/compare/0.2.2...0.3.0

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "interchange"
-version = "0.3.2"
+version = "0.3.3"
 authors = ["The Trussed developers", "Nicolas Stalder <n@stalder.io>"]
 edition = "2018"
 description = "Request/response mechanism for embedded development, using atomics"

src/lib.rs

@@ -75,7 +75,7 @@
 //! assert!(rq.request(request).is_ok());
 //! let request = rp.take_request().unwrap();
 //!
-//! println!("responder could cancel: {:?}", &rq.cancel().unwrap().is_none());
+//! println!("responder could cancel: {:?}", rq.cancel().unwrap().is_none());
 //! assert!(rp.is_canceled());
 //! assert!(rp.respond(response).is_err());
 //! assert!(rp.acknowledge_cancel().is_ok());
@@ -171,6 +171,9 @@ impl From<u8> for State {
     }
 }
 
+/// Callback that can be called
+pub type Callback = fn();
+
 // the repr(u8) is necessary so MaybeUninit::zeroized.assume_init() is valid and corresponds to
 // None
 #[repr(u8)]
@@ -291,7 +294,7 @@ impl<Rq, Rp> Message<Rq, Rp> {
 /// assert!(rq.request(request).is_ok());
 /// let request = rp.take_request().unwrap();
 ///
-/// println!("responder could cancel: {:?}", &rq.cancel().unwrap().is_none());
+/// println!("responder could cancel: {:?}", rq.cancel().unwrap().is_none());
 /// assert!(rp.is_canceled());
 /// assert!(rp.respond(response).is_err());
 /// assert!(rp.acknowledge_cancel().is_ok());
@@ -361,7 +364,10 @@ impl<Rq, Rp> Channel<Rq, Rp> {
             .compare_exchange(false, true, Ordering::Relaxed, Ordering::Relaxed)
             .is_ok()
         {
-            Some(Requester { channel: self })
+            Some(Requester {
+                channel: self,
+                callback: || {},
+            })
         } else {
             None
         }
@@ -376,7 +382,10 @@ impl<Rq, Rp> Channel<Rq, Rp> {
             .compare_exchange(false, true, Ordering::Relaxed, Ordering::Relaxed)
             .is_ok()
         {
-            Some(Responder { channel: self })
+            Some(Responder {
+                channel: self,
+                callback: || {},
+            })
         } else {
             None
         }
@@ -408,6 +417,7 @@ impl<Rq, Rp> Default for Channel<Rq, Rp> {
 /// the requester uses a `'static` lifetime parameter
 pub struct Requester<'i, Rq, Rp> {
     channel: &'i Channel<Rq, Rp>,
+    callback: Callback,
 }
 
 impl<Rq, Rp> Drop for Requester<'_, Rq, Rp> {
@@ -419,6 +429,15 @@ impl<Rq, Rp> Drop for Requester<'_, Rq, Rp> {
 }
 
 impl<'i, Rq, Rp> Requester<'i, Rq, Rp> {
+    /// Allows to set a callback that is called when a request has been sent and when a request
+    /// has been cancelled before it was taken by the responder.
+    ///
+    /// The callback is called by [`Requester::request`][], [`Requester::send_request`][] and
+    /// [`Requester::cancel`][].
+    pub fn callback_mut(&mut self) -> &mut Callback {
+        &mut self.callback
+    }
+
     pub fn channel(&self) -> &'i Channel<Rq, Rp> {
         self.channel
     }
@@ -467,10 +486,13 @@ impl<'i, Rq, Rp> Requester<'i, Rq, Rp> {
     /// Send a request to the responder.
     ///
     /// If efficiency is a concern, or requests need multiple steps to
-    /// construct, use `request_mut` and `send_request.
+    /// construct, use `request_mut` and `send_request`.
     ///
     /// If the RPC state is `Idle`, this always succeeds, else calling
     /// is a logic error and the request is returned.
+    ///
+    /// If the request has been sent succesfully, this functions calls the callback set with
+    /// [`Requester::callback_mut`][].
     pub fn request(&mut self, request: Rq) -> Result<(), Error> {
         if State::Idle == self.channel.state.load(Ordering::Acquire) {
             unsafe {
@@ -479,6 +501,7 @@ impl<'i, Rq, Rp> Requester<'i, Rq, Rp> {
             self.channel
                 .state
                 .store(State::Requested as u8, Ordering::Release);
+            (self.callback)();
             Ok(())
         } else {
             Err(Error)
@@ -493,6 +516,9 @@ impl<'i, Rq, Rp> Requester<'i, Rq, Rp> {
     /// If the responder has taken the request (is processing), we succeed and return None.
     ///
     /// In other cases (`Idle` or `Reponsed`) there is nothing to cancel and we fail.
+    ///
+    /// If the responder has not taken the request yet, this functions calls the callback set
+    /// with [`Requester::callback_mut`][].
     pub fn cancel(&mut self) -> Result<Option<Rq>, Error> {
         if self
             .channel
@@ -503,6 +529,7 @@ impl<'i, Rq, Rp> Requester<'i, Rq, Rp> {
         }
 
         if self.channel.transition(State::Requested, State::Idle) {
+            (self.callback)();
             // we canceled before the responder was even aware of the request.
             return Ok(Some(unsafe { self.with_data_mut(|i| i.take_rq()) }));
         }
@@ -605,12 +632,16 @@ where
 
     /// Send a request that was already placed in the channel using `request_mut` or
     /// `with_request_mut`.
+    ///
+    /// If the request has been sent succesfully, this functions calls the callback set with
+    /// [`Requester::callback_mut`][].
     pub fn send_request(&mut self) -> Result<(), Error> {
         if State::BuildingRequest == self.channel.state.load(Ordering::Acquire)
             && self
                 .channel
                 .transition(State::BuildingRequest, State::Requested)
         {
+            (self.callback)();
             Ok(())
         } else {
             // logic error
@@ -625,6 +656,7 @@ where
 /// the responder uses a `'static` lifetime parameter
 pub struct Responder<'i, Rq, Rp> {
     channel: &'i Channel<Rq, Rp>,
+    callback: Callback,
 }
 
 impl<Rq, Rp> Drop for Responder<'_, Rq, Rp> {
@@ -636,6 +668,13 @@ impl<Rq, Rp> Drop for Responder<'_, Rq, Rp> {
 }
 
 impl<'i, Rq, Rp> Responder<'i, Rq, Rp> {
+    /// Allows to set a callback that is called when a response has been sent.
+    ///
+    /// The callback is called by [`Responder::respond`][] and [`Responder::send_response`][].
+    pub fn callback_mut(&mut self) -> &mut Callback {
+        &mut self.callback
+    }
+
     pub fn channel(&self) -> &'i Channel<Rq, Rp> {
         self.channel
     }
@@ -749,6 +788,8 @@ impl<'i, Rq, Rp> Responder<'i, Rq, Rp> {
     /// If efficiency is a concern, or responses need multiple steps to
     /// construct, use `with_response_mut` or `response_mut` and `send_response`.
     ///
+    /// If the response has been sent succesfully, this functions calls the callback set with
+    /// [`Responder::callback_mut`][].
     pub fn respond(&mut self, response: Rp) -> Result<(), Error> {
         if State::BuildingResponse == self.channel.state.load(Ordering::Acquire) {
             unsafe {
@@ -758,6 +799,7 @@ impl<'i, Rq, Rp> Responder<'i, Rq, Rp> {
                 .channel
                 .transition(State::BuildingResponse, State::Responded)
             {
+                (self.callback)();
                 Ok(())
             } else {
                 Err(Error)
@@ -826,12 +868,16 @@ where
 
     /// Send a response that was already placed in the channel using `response_mut` or
     /// `with_response_mut`.
+    ///
+    /// If the response has been sent succesfully, this functions calls the callback set with
+    /// [`Responder::callback_mut`][].
     pub fn send_response(&mut self) -> Result<(), Error> {
         if State::BuildingResponse == self.channel.state.load(Ordering::Acquire)
             && self
                 .channel
                 .transition(State::BuildingResponse, State::Responded)
         {
+            (self.callback)();
             Ok(())
         } else {
             // logic error
@@ -901,7 +947,7 @@ impl<Rq, Rp, const N: usize> Interchange<Rq, Rp, N> {
     }
 
     /// Claim one of the channels of the interchange. Returns None if called more than `N` times.
-    pub fn claim(&self) -> Option<(Requester<Rq, Rp>, Responder<Rq, Rp>)> {
+    pub fn claim(&'_ self) -> Option<(Requester<'_, Rq, Rp>, Responder<'_, Rq, Rp>)> {
         self.as_interchange_ref().claim()
     }
 
@@ -1078,7 +1124,7 @@ mod tests {
         let request = rp.take_request().unwrap();
         println!(
             "responder could cancel: {:?}",
-            &rq.cancel().unwrap().is_none()
+            rq.cancel().unwrap().is_none()
         );
         assert_eq!(request, Request::This(1, 2));
         assert!(rp.is_canceled());
@@ -1127,7 +1173,7 @@ mod tests {
         let request = rp.take_request().unwrap();
         println!(
             "responder could cancel: {:?}",
-            &rq.cancel().unwrap().is_none()
+            rq.cancel().unwrap().is_none()
         );
         assert_eq!(request, Request::This(1, 2));
         assert!(rp.is_canceled());