Crate safina_sync

ARCHIVED ARCHIVED ARCHIVED

This crate is archived and will not be updated.

The code is now at safina::sync in the safina crate.

---

safina-sync

Structs for sharing or sending data between async tasks.

It is part of safina, a safe async runtime.

Features

• Mutex with an async lock method
• oneshot and sync_channel with async and blocking methods
• forbid(unsafe_code)
• Depends only on std
• 100% test coverage
• Works with safina-executor or any async executor

Limitations

• Allocates
• No const constructor. Uses std::sync::Mutex internally, which does not have a const constructor. See rust#66806 and const-eval#3. You can work around this with unstable core::lazy::OnceCell or various unsafe crates: lazy_static, once_cell, lazycell, and conquer-once.

Documentation

https://docs.rs/safina-sync

Examples

use std::sync::Arc;
use safina_async_test::async_test;
use safina_sync::Mutex;
let shared_counter: Arc<Mutex<u32>> = get_shared_data();
{
    let mut counter_guard = shared_counter.lock().await;
    *counter_guard += 1;
    // some_async_fn().await; // Cannot await while holding a MutexGuard.
}
some_async_fn().await; // Await is ok after releasing MutexGuard.

Alternatives

• async-lock
  • Contains a little unsafe code
• futures-locks
  • Contains a little unsafe code
• futures-util
  • Very popular
  • Full of unsafe
• tokio-sync
  • Very popular
  • Fast
  • Internally incredibly complicated
  • Full of unsafe

Changelog

• v0.2.4
  • Implement Eq and PartialEq for Receiver, OneSender, and SyncSender.
  • Fix bug where await on Receiver would not wake senders.
• v0.2.3 Fix race condition.
• v0.2.2 Fix deadlock on Linux.
• v0.2.1
  • Add sync_channel and SyncSender.
  • Add Receiver::async_recv to let users await without writing ugly (&mut receiver).await.
  • Remove Receiver::blocking and add try_recv, recv, etc.
• v0.2.0 - Replace Promise with oneshot, OneSender, and Receiver that supports async and blocking reads.
• v0.1.6 - Update docs.
• v0.1.5 - Update docs
• v0.1.4 - Update docs, make MutexGuard::new non-public
• v0.1.3 - Fix Promise type parameter
• v0.1.2 - Add Promise
• v0.1.1 - Improve Mutex performance when there are many waiters
• v0.1.0 - First published version

TO DO

• Add Barrier
• Add RwLock
• Add WaitableBool
• Add UnboundedChannel
• Add WaitableQueue (multiple receivers)
• Add UnboundedWaitableQueue
• Add Topic (copies message to every receiver)

Release Process

1. Edit Cargo.toml and bump version number.
2. Run ./release.sh

Structs

Inner

IntoIter

An owning iterator over messages on a Receiver, created by into_iter.

Iter

An iterator over messages on a Receiver, created by iter.

Mutex

A wrapper around std::sync::Mutex with an async lock method.

MutexGuard

An RAII scoped lock of a Mutex. It automatically unlocks the mutex when dropped (falls out of scope).

OneSender

Receiver

The receiving half of a channel. This half can only be owned by one thread.

SendFut

SyncSender

TryIter

An iterator that attempts to yield all pending values for a Receiver, created by try_iter.

Functions

oneshot

Creates a channel that can be used to send a single value.

sync_channel

Creates a new synchronous, bounded channel. All data sent on the SyncSender will become available on the Receiver in the same order as it was sent. The Receiver will block until a message becomes available.