1.2.0 release

Author: danielstuart14

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
+## 1.2.0 - 2024-09-17
+
+- Switch to `portable-atomic`
+
 ## 1.1.0 - 2024-08-19
 
 - Add async functionality

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "async-pool"
-version = "1.1.1"
+version = "1.2.0"
 authors = ["Daniel Stuart <[email protected]>"]
 description = "Statically allocated pool providing a std-like Box, with async functionality."
 repository = "https://github.com/danielstuart14/async-pool"

README.md

@@ -2,13 +2,38 @@
 
 [![Documentation](https://docs.rs/async-pool/badge.svg)](https://docs.rs/async-pool)
 
-Statically allocated pool providing a std-like Box, with hability to asynchronously wait for a pool slot to become available. 
+Statically allocated pool providing a std-like Box, allowing to asynchronously await for a pool slot to become available. 
 
-This crate is tailored to be used with no-std async runtimes, like [Embassy](https://embassy.dev/), but can also be used in std environments (check examples).
+It is tailored to be used with no-std async runtimes, like [Embassy](https://embassy.dev/), but can also be used in std environments (check examples). 
+
+The most common use-case is sharing large memory regions on constrained devices (e.g. microcontrollers), where multiple tasks may need to use the memory for buffering an I/O or performing calculations, and having separate static buffers would be too costly.
+
+It is important to know that waiting forever for a memory slot to be available may dead-lock your code if done wrong. With that in mind, you should consider using a timeout when allocating asynchronously (e.g. [embassy_time::with_timeout](https://docs.rs/embassy-time/0.3.2/embassy_time/fn.with_timeout.html)).
 
 ## Dependencies 
 
-This crate uses the `AtomicWaker` functionality from `embassy-sync` crate, which in turn requires a critical section implementation. Check [critical-section](https://crates.io/crates/critical-section).
+This crate requires a critical section implementation. Check [critical-section](https://crates.io/crates/critical-section).
+
+## Example
+
+```
+use async_pool::{pool, Box};
+
+struct Buffer([u8; 256]);
+
+// A maximum of 2 Packet instances can be allocated at a time.
+// A maximum of 3 futures can be waiting at a time.
+pool!(BufferPool: [Buffer; 2], 3);
+
+async fn run() {
+    // Allocate non-blocking (will return None if no data slot is available)
+    let box1 = Box::<BufferPool>::new(Buffer([0; 256]));
+
+    // Allocate asynchronously (will wait if no data slot is available)
+    // This can return None if all future slots are taken
+    let box2 = Box::<BufferPool>::new_async(Buffer([0; 256])).await;
+}
+```
 
 ## Previous work
 

examples/tokio.rs

@@ -1,7 +1,7 @@
 //! This example demonstrates the use of the `async_pool` crate with the `tokio` framework.
 
-use tokio::time::sleep;
 use tokio::join;
+use tokio::time::sleep;
 
 use std::mem;
 use std::time::Duration;
@@ -72,4 +72,4 @@ async fn main() {
     };
 
     join!(fut1, fut2, fut3, fut4, fut5);
-}
+}

src/atomic_bitset.rs

@@ -20,7 +20,8 @@ where
     }
 
     pub fn alloc_droppable(&self) -> Option<droppable_bit::DroppableBit<N, K>> {
-        self.alloc().map(|i| droppable_bit::DroppableBit::new(self, i))
+        self.alloc()
+            .map(|i| droppable_bit::DroppableBit::new(self, i))
     }
 
     pub fn alloc(&self) -> Option<usize> {

src/atomic_bitset/droppable_bit.rs

@@ -49,4 +49,4 @@ mod test {
         v.pop();
         assert!(s.alloc().is_some());
     }
-}
+}

src/lib.rs

@@ -1,8 +1,46 @@
+//! Statically allocated pool providing a std-like Box,
+//! allowing to asynchronously await for a pool slot to become available.
+//!
+//! It is tailored to be used with no-std async runtimes, like [Embassy](https://embassy.dev/), but
+//! can also be used in std environments (check examples).
+//!
+//! The most common use-case is sharing large memory regions on constrained
+//! devices (e.g. microcontrollers), where multiple tasks may need to use the
+//! memory for buffering an I/O or performing calculations, and having
+//! separate static buffers would be too costly.
+//!
+//! It is important to know that waiting forever for a memory slot to be
+//! available may dead-lock your code if done wrong. With that in mind,
+//! you should consider using a timeout when allocating asynchronously (e.g. [embassy_time::with_timeout](https://docs.rs/embassy-time/0.3.2/embassy_time/fn.with_timeout.html)).
+//!
+//! #### Dependencies
+//!
+//! This crate requires a critical section implementation. Check [critical-section](https://crates.io/crates/critical-section).
+//!
+//! #### Example
+//!
+//! ```
+//! use async_pool::{pool, Box};
+//!
+//!struct Buffer([u8; 256]);
+//!
+//!// A maximum of 2 Packet instances can be allocated at a time.
+//!// A maximum of 3 futures can be waiting at a time.
+//!pool!(BufferPool: [Buffer; 2], 3);
+//!
+//!async fn run() {
+//!    // Allocate non-blocking (will return None if no data slot is available)
+//!    let box1 = Box::<BufferPool>::new(Buffer([0; 256]));
+//!
+//!    // Allocate asynchronously (will wait if no data slot is available)
+//!    // This can return None if all future slots are taken
+//!    let box2 = Box::<BufferPool>::new_async(Buffer([0; 256])).await;
+//!}
+//! ```
 #![cfg_attr(not(test), no_std)]
 
 mod atomic_bitset;
 
-use portable_atomic::AtomicU32;
 use core::cell::UnsafeCell;
 use core::future::{poll_fn, Future};
 use core::hash::{Hash, Hasher};
@@ -11,6 +49,7 @@ use core::ops::{Deref, DerefMut};
 use core::task::Poll;
 use core::{cmp, mem, ptr::NonNull};
 use embassy_sync::waitqueue::AtomicWaker;
+use portable_atomic::AtomicU32;
 
 use crate::atomic_bitset::AtomicBitset;
 
@@ -299,7 +338,7 @@ where
 }
 
 /// Create a item pool of a given type and size, as well as a waker pool of a given length.
-/// 
+///
 /// The waker pool is used to wake up tasks waiting for an item to become available in the data pool.
 /// Its length should be at least the number of tasks that can be waiting for an item at the same time.
 /// Example: