Skip to content

Commit

Permalink
move lib doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@andylokandy
andylokandy committed Nov 3, 2024
1 parent 8d48f06 commit c3c4abb
Show file tree
Hide file tree
Showing 6 changed files with 155 additions and 153 deletions.
28 changes: 28 additions & 0 deletions mea/src/barrier/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,34 @@
// See the License for the specific language governing permissions and
// limitations under the License.

//! A synchronization primitive that enables multiple tasks to wait for each other.
//!
//! The barrier ensures that no task proceeds past a certain point until all tasks have reached it.
//! This is useful for scenarios where multiple tasks need to proceed together after reaching a
//! certain point in their execution.
//!
//! # Examples
//!
//! ```
//! use std::sync::Arc;
//!
//! use mea::barrier::Barrier;
//!
//! async fn example() {
//! let barrier = Arc::new(Barrier::new(3));
//! let mut handles = Vec::new();
//!
//! for i in 0..3 {
//! let barrier = barrier.clone();
//! handles.push(tokio::spawn(async move {
//! println!("Task {} before barrier", i);
//! let is_leader = barrier.wait().await;
//! println!("Task {} after barrier (leader: {})", i, is_leader);
//! }));
//! }
//! }
//! ```

use std::fmt;
use std::future::Future;
use std::pin::Pin;
Expand Down
32 changes: 32 additions & 0 deletions mea/src/latch/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,38 @@
// See the License for the specific language governing permissions and
// limitations under the License.

//! A countdown latch that allows one or more tasks to wait until a set of operations completes.
//!
//! Unlike a barrier, a latch's count can only decrease and cannot be reused once it reaches zero.
//! This makes it ideal for scenarios where you need to wait for a specific number of events or
//! operations to complete.
//!
//! # Examples
//!
//! ```
//! use std::sync::Arc;
//!
//! use mea::latch::Latch;
//!
//! async fn example() {
//! let latch = Arc::new(Latch::new(3));
//! let mut handles = Vec::new();
//!
//! for i in 0..3 {
//! let latch = latch.clone();
//! handles.push(tokio::spawn(async move {
//! println!("Task {} starting", i);
//! // Simulate some work
//! latch.count_down(); // Signal completion
//! }));
//! }
//!
//! // Wait for all tasks to complete
//! latch.wait().await;
//! println!("All tasks completed");
//! }
//! ```

use std::fmt;
use std::future::Future;
use std::pin::Pin;
Expand Down
152 changes: 0 additions & 152 deletions mea/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,162 +50,10 @@

mod internal;

/// A synchronization primitive that enables multiple tasks to wait for each other.
///
/// The barrier ensures that no task proceeds past a certain point until all tasks have reached it.
/// This is useful for scenarios where multiple tasks need to proceed together after reaching a
/// certain point in their execution.
///
/// # Examples
///
/// ```
/// use std::sync::Arc;
///
/// use mea::barrier::Barrier;
///
/// async fn example() {
/// let barrier = Arc::new(Barrier::new(3));
/// let mut handles = Vec::new();
///
/// for i in 0..3 {
/// let barrier = barrier.clone();
/// handles.push(tokio::spawn(async move {
/// println!("Task {} before barrier", i);
/// let is_leader = barrier.wait().await;
/// println!("Task {} after barrier (leader: {})", i, is_leader);
/// }));
/// }
/// }
/// ```
pub mod barrier;

/// A countdown latch that allows one or more tasks to wait until a set of operations completes.
///
/// Unlike a barrier, a latch's count can only decrease and cannot be reused once it reaches zero.
/// This makes it ideal for scenarios where you need to wait for a specific number of events or
/// operations to complete.
///
/// # Examples
///
/// ```
/// use std::sync::Arc;
///
/// use mea::latch::Latch;
///
/// async fn example() {
/// let latch = Arc::new(Latch::new(3));
/// let mut handles = Vec::new();
///
/// for i in 0..3 {
/// let latch = latch.clone();
/// handles.push(tokio::spawn(async move {
/// println!("Task {} starting", i);
/// // Simulate some work
/// latch.count_down(); // Signal completion
/// }));
/// }
///
/// // Wait for all tasks to complete
/// latch.wait().await;
/// println!("All tasks completed");
/// }
/// ```
pub mod latch;

/// An async mutex for protecting shared data.
///
/// Unlike a standard mutex, this implementation is designed to work with async/await,
/// ensuring tasks yield properly when the lock is contended. This makes it suitable
/// for protecting shared resources in async code.
///
/// # Examples
///
/// ```
/// use std::sync::Arc;
///
/// use mea::mutex::Mutex;
///
/// async fn example() {
/// let mutex = Arc::new(Mutex::new(0));
/// let mut handles = Vec::new();
///
/// for i in 0..3 {
/// let mutex = mutex.clone();
/// handles.push(tokio::spawn(async move {
/// let mut lock = mutex.lock().await;
/// *lock += i;
/// }));
/// }
/// }
/// ```
pub mod mutex;

/// A counting semaphore for controlling access to a pool of resources.
///
/// Semaphores can be used to limit the number of tasks that can access a resource
/// simultaneously. This is particularly useful for implementing connection pools,
/// rate limiters, or any scenario where you need to control concurrent access to
/// limited resources.
///
/// # Examples
///
/// ```
/// use std::sync::Arc;
///
/// use mea::semaphore::Semaphore;
///
/// struct ConnectionPool {
/// sem: Arc<Semaphore>,
/// }
///
/// impl ConnectionPool {
/// fn new(size: u32) -> Self {
/// Self {
/// sem: Arc::new(Semaphore::new(size)),
/// }
/// }
///
/// async fn get_connection(&self) -> Connection {
/// let _permit = self.sem.acquire(1).await;
/// Connection {} // Acquire and return a connection
/// }
/// }
///
/// struct Connection {}
/// ```
pub mod semaphore;

/// A synchronization primitive for waiting on multiple tasks to complete.
///
/// Similar to Go's WaitGroup, this type allows a task to wait for multiple other
/// tasks to finish. Each task holds a handle to the WaitGroup, and the main task
/// can wait for all handles to be dropped before proceeding.
///
/// # Examples
///
/// ```
/// use std::time::Duration;
///
/// use mea::waitgroup::WaitGroup;
///
/// async fn example() {
/// let wg = WaitGroup::new();
/// let mut handles = Vec::new();
///
/// for i in 0..3 {
/// let wg = wg.clone();
/// handles.push(tokio::spawn(async move {
/// println!("Task {} starting", i);
/// tokio::time::sleep(Duration::from_millis(100)).await;
/// // wg is automatically decremented when dropped
/// }));
/// }
///
/// // Wait for all tasks to complete
/// wg.await;
/// println!("All tasks completed");
/// }
/// ```
pub mod waitgroup;

#[cfg(test)]
Expand Down
30 changes: 29 additions & 1 deletion mea/src/mutex/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,33 @@
// See the License for the specific language governing permissions and
// limitations under the License.

//! An async mutex for protecting shared data.
//!
//! Unlike a standard mutex, this implementation is designed to work with async/await,
//! ensuring tasks yield properly when the lock is contended. This makes it suitable
//! for protecting shared resources in async code.
//!
//! # Examples
//!
//! ```
//! use std::sync::Arc;
//!
//! use mea::mutex::Mutex;
//!
//! async fn example() {
//! let mutex = Arc::new(Mutex::new(0));
//! let mut handles = Vec::new();
//!
//! for i in 0..3 {
//! let mutex = mutex.clone();
//! handles.push(tokio::spawn(async move {
//! let mut lock = mutex.lock().await;
//! *lock += i;
//! }));
//! }
//! }
//! ```

use std::cell::UnsafeCell;
use std::fmt;
use std::ops::Deref;
Expand Down Expand Up @@ -147,7 +174,8 @@ impl<T: ?Sized> Mutex<T> {
/// use mea::mutex::Mutex;
///
/// let mutex = Mutex::new(1);
/// match mutex.try_lock() {
/// let guard = mutex.try_lock();
/// match guard {
/// Some(mut guard) => {
/// *guard += 1;
/// }
Expand Down
34 changes: 34 additions & 0 deletions mea/src/semaphore/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,40 @@
// See the License for the specific language governing permissions and
// limitations under the License.

//! A counting semaphore for controlling access to a pool of resources.
//!
//! Semaphores can be used to limit the number of tasks that can access a resource
//! simultaneously. This is particularly useful for implementing connection pools,
//! rate limiters, or any scenario where you need to control concurrent access to
//! limited resources.
//!
//! # Examples
//!
//! ```
//! use std::sync::Arc;
//!
//! use mea::semaphore::Semaphore;
//!
//! struct ConnectionPool {
//! sem: Arc<Semaphore>,
//! }
//!
//! impl ConnectionPool {
//! fn new(size: u32) -> Self {
//! Self {
//! sem: Arc::new(Semaphore::new(size)),
//! }
//! }
//!
//! async fn get_connection(&self) -> Connection {
//! let _permit = self.sem.acquire(1).await;
//! Connection {} // Acquire and return a connection
//! }
//! }
//!
//! struct Connection {}
//! ```

use crate::internal;

#[cfg(test)]
Expand Down
32 changes: 32 additions & 0 deletions mea/src/waitgroup/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,38 @@
// See the License for the specific language governing permissions and
// limitations under the License.

//! A synchronization primitive for waiting on multiple tasks to complete.
//!
//! Similar to Go's WaitGroup, this type allows a task to wait for multiple other
//! tasks to finish. Each task holds a handle to the WaitGroup, and the main task
//! can wait for all handles to be dropped before proceeding.
//!
//! # Examples
//!
//! ```
//! use std::time::Duration;
//!
//! use mea::waitgroup::WaitGroup;
//!
//! async fn example() {
//! let wg = WaitGroup::new();
//! let mut handles = Vec::new();
//!
//! for i in 0..3 {
//! let wg = wg.clone();
//! handles.push(tokio::spawn(async move {
//! println!("Task {} starting", i);
//! tokio::time::sleep(Duration::from_millis(100)).await;
//! // wg is automatically decremented when dropped
//! }));
//! }
//!
//! // Wait for all tasks to complete
//! wg.await;
//! println!("All tasks completed");
//! }
//! ```

use std::fmt;
use std::future::Future;
use std::future::IntoFuture;
Expand Down

0 comments on commit c3c4abb

Please sign in to comment.