Merge pull request #10 from ChrisRega/0.3.2-dev

0.4.0-release

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lazy_async_promise"
-version = "0.4.0-RC1"
+version = "0.4.0"
 edition = "2021"
 authors = ["Christopher Regali <christopher.regali@vdop.org>"]
 license = "MIT"
@@ -16,3 +16,4 @@ tokio = {version="1", features=["rt-multi-thread", "sync"]}
 
 [dev-dependencies]
 tokio = {version="1", features=["rt-multi-thread", "sync", "time", "fs"]}
+

README.md

@@ -2,7 +2,7 @@
 [![Documentation](https://docs.rs/lazy_async_promise/badge.svg)](https://docs.rs/lazy_async_promise)
 ![CI](https://github.com/ChrisRega/lazy_async_promise/actions/workflows/rust.yml/badge.svg?branch=main "CI")
 [![Coverage Status](https://coveralls.io/repos/github/ChrisRega/lazy_async_promise/badge.svg?branch=main)](https://coveralls.io/github/ChrisRega/lazy_async_promise?branch=main)
-[![License](https://img.shields.io/badge/license-MIT-blue?style=flat)](LICENSE-MIT)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=flat)](LICENSE)
 
 
 This crate currently only features simple primitives for getting computation time off the main thread using tokio:
@@ -12,13 +12,20 @@ This crate currently only features simple primitives for getting computation tim
 As the name suggests the two of them are lazily evaluated and nothing happens until they are polled for the first time.
 
 For single values which are either available or not there's `ImmediateValuePromise` which triggers computation immediately.
-There's not in-calculation value read out, so either it's finished or not. 
-
-Example-usage of this crate with a small egui/eframe blog-reader can be found [here](https://github.com/ChrisRega/example-blog-client/)
+There's not in-calculation value read out, so either it's finished or not.
+After heavy usage, I currently tend to use `ImmediateValuePromise` wrapped in `Option` for most lazy values, too.
+Especially when no intermediate values are needed, it's technically sufficient and simpler. 
+Also, since 0.4.0 it's very convenient to use now, see the docs for examples.
 
+Another example usage of this crate with a small egui/eframe blog-reader can be found [here](https://github.com/ChrisRega/example-blog-client/)
 
 Changelog:
 
+0.4.0:
+- Added more flexible API to lazy and immediate structures, allowing to take the values
+- Added DirectCacheAccess trait to make option-based usage of the immediate value promise more convenient
+- Updated documentation
+
 0.3.1:
 - Add better api macros for lazy structures
 

src/immediatevalue.rs

@@ -111,7 +111,7 @@ impl Deref for BoxedSendError {
 /// promise_ref.poll_state();
 /// thread::sleep(Duration::from_millis(50));
 /// //now let's assume we forgot about our lease already and want to get the value again:
-/// let value_opt = state.promise.as_ref().unwrap().get_value(); // <- don't do this
+/// let value_opt = state.promise.as_ref().unwrap().get_value(); // <- dangerous
 /// let value_opt = state.promise.as_ref().and_then(|i| i.get_value()); // <- better, but still ugly
 /// let value_opt = state.promise.get_value(); // <- way nicer!
 /// assert!(value_opt.is_some());

src/lazyvalue.rs

@@ -25,14 +25,18 @@ use tokio::sync::mpsc::{channel, Receiver, Sender};
 /// // direct usage:
 /// let promise = LazyValuePromise::new(updater, 10);
 /// // for usage of the progress, see the docs of [`LazyVecPromise`]
-/// fn main_loop(lazy_promise: &mut  LazyValuePromise<i32>) {
+/// fn main_loop(mut  lazy_promise: LazyValuePromise<i32>) {
 ///   loop {
 ///     match lazy_promise.poll_state() {
 ///       DataState::Error(er)  => { println!("Error {} occurred! Retrying!", er); std::thread::sleep(Duration::from_millis(500)); lazy_promise.update(); }
 ///       DataState::UpToDate   => { println!("Value up2date: {}", lazy_promise.get_value().unwrap()); }
 ///                           _ => { println!("Still updating... might be in strange state! (current state: {:?}", lazy_promise.get_value()); }
 ///     }
 ///   }
+///
+///   // Also, we can use all of DirectCacheAccess:
+///    let current_cache = lazy_promise.get_value();
+///    let current_cache_mut = lazy_promise.get_value_mut();
 /// }
 /// ```
 ///

src/lazyvec.rs

@@ -13,7 +13,7 @@ use tokio::sync::mpsc::{channel, Receiver, Sender};
 /// ```rust, no_run
 /// use std::time::Duration;
 /// use tokio::sync::mpsc::Sender;
-/// use lazy_async_promise::{DataState, Message, Promise, LazyVecPromise, api_macros::*};
+/// use lazy_async_promise::{DataState, Message, Promise, LazyVecPromise, api_macros::*, DirectCacheAccess};
 /// // updater-future:
 /// let updater = |tx: Sender<Message<i32>>| async move {
 ///   const ITEM_COUNT: i32 = 100;
@@ -32,7 +32,7 @@ use tokio::sync::mpsc::{channel, Receiver, Sender};
 /// // direct usage:
 /// let promise = LazyVecPromise::new(updater, 200);
 ///
-/// fn main_loop(lazy_promise: &mut LazyVecPromise<i32>) {
+/// fn main_loop(mut lazy_promise: LazyVecPromise<i32>) {
 ///   loop {
 ///     let state = lazy_promise.poll_state();
 ///     let progress = state.get_progress().unwrap_or_default();
@@ -42,6 +42,9 @@ use tokio::sync::mpsc::{channel, Receiver, Sender};
 ///                           _ => { println!("Getting data, might be partially ready! (part: {:?} - progress: {}", lazy_promise.as_slice(), progress.as_f32()); }  
 ///     }
 ///   }
+///   // Also, we can use DirectCacheAccess:
+///    let current_cache = lazy_promise.get_value();
+///    let current_cache_mut = lazy_promise.get_value_mut();
 /// }
 /// ```
 ///

src/lib.rs

@@ -6,7 +6,7 @@
 //! - [`ImmediateValuePromise`]: An immediately updating async-enabled single value promise
 //! See these items for their respective documentation. A general usage guide would be:
 //! - You want several items of the same kind displayed / streamed? Use: [`LazyVecPromise`]
-//! - You want one item displayed when ready and need lazy evaluation or have intermediate results? Use: [`LazyVecPromise`]
+//! - You want one item displayed when ready and need lazy evaluation or have intermediate results? Use: [`LazyValuePromise`]
 //! - You just want one item displayed when ready? Use: [`ImmediateValuePromise`] (for laziness wrap in `Option`)
 #![deny(missing_docs)]
 #![deny(unused_qualifications)]