asyncband/once/mod.rs
1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements. See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership. The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License. You may obtain a copy of the License at
8//
9// http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied. See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18//! Asynchronous primitives for one-time coordination.
19//!
20//! # Choosing a primitive
21//!
22//! * `Once` runs a side-effecting initializer successfully once without storing a value. A
23//! cancelled or panicked attempt leaves it available for another caller to retry.
24//! * `OnceCell` stores one value from an initializer supplied at access time. Failed, cancelled, or
25//! panicked attempts leave the cell empty and retryable.
26//! * `LazyCell` owns one initializer and preserves the same in-flight future across caller
27//! cancellation. A panic poisons the cell instead of starting another attempt.
28//! * `OnceMap` applies retryable `OnceCell` initialization per key and retains successful values
29//! until they are explicitly removed.
30//!
31//! These primitives retain completed state. Use `singleflight::Group` when only overlapping calls
32//! for a key should share work and later calls should execute again.
33
34#[cfg(feature = "lazy-cell")]
35mod lazy_cell;
36#[cfg(feature = "once")]
37mod once;
38#[cfg(feature = "once-cell")]
39mod once_cell;
40#[cfg(feature = "once-map")]
41mod once_map;
42
43#[cfg(feature = "lazy-cell")]
44pub use self::lazy_cell::LazyCell;
45#[cfg(feature = "once")]
46pub use self::once::Once;
47#[cfg(feature = "once-cell")]
48pub use self::once_cell::OnceCell;
49#[cfg(feature = "once-map")]
50pub use self::once_map::OnceMap;