[![Build Status](https://gitlab.com/BrightOpen/potential/badges/master/pipeline.svg)](https://gitlab.com/BrightOpen/potential/commits/master)
![Maintenance](https://img.shields.io/badge/maintenance-activly--developed-brightgreen.svg)

# potential 2.2.1

Borrowing for futures - a bit like `Option`, but async and with a return channel.
A bit like a `Mutex`, compensating for `MutexGuard` not being safe to send.
The item is moved (leased) from the owner Potential into the Lease.
When the Lease is dropped, the item is sent back to the owner.
Owner of the Potential can await the return of the leased item.

It is geared towards asynchronous servers. The use case is that
some resources can or should be reused, such as TCP connections
or crypto configuration or backend storage but they need to be
sent off with futures where there is no track of the _future_
of the shared resource unless &mut is used so single copy is
guaranteed, Mutex is used with a lifetime bound for the future
or you use Potential which allows you not to bind the future lifetime
to the source. Still, only one running future/task can use the resource
at a time. The owner can thus control the concurrency which is by default 1
and can be increased by resetting the Potential to a new value.

If the lease is not dropped properly (such as if you `mem::forget()` it
or when its thread panics badly), the `Potential` calls will be stuck forever.
If you suspect that this may happen, await with a timeout to be able to recover.

## Sync + Send future example
  Notice the mutation of String through immutable reference,
  initializing the potential through a lease,
  and that futures are Sync + Send.
  Futures on a lease naturally serialize (are mutually exclusive).
```rust
use potential::Potential;
use std::future::Future;
use std::task::Poll;
use std::pin::Pin;
#[derive(Default)]
struct Trial {
    inner: Potential<String>
}
impl Trial {
    async fn back_to_the_future(&self, item:String) -> usize {
        let mut lease = match self.inner.lease().await {
            Ok(lease) => lease,
            Err(gone) => gone.set(String::new())
        };
        // here some other async work...
        lease.extend(item.chars());
        lease.len()
    }
}
async fn test(trial: &Trial) -> String {
    let fut2 = trial.back_to_the_future(" and then".to_owned());
    let fut1 = trial.back_to_the_future("now".to_owned());
    assert_eq!(fut1.await, 3);
    assert_eq!(fut2.await, 12);
    trial.inner.lease().await.expect("set").clone()
}
let trial = Trial::default();
let mut fut = test(&trial);
assert_eq!(Box::pin(fut).as_mut().poll(&mut cx()), Poll::Ready("now and then".to_owned()));

is_sync_and_send(test(&trial));
fn is_sync_and_send<T: Sync + Send>(_: T) {};
fn cx() -> std::task::Context<'static> {
    let waker = futures_util::task::noop_waker_ref();
    let cx = std::task::Context::from_waker(waker);
    cx
};
```

## Example: 'static + Sync + Send future with Arc
Not sure how to pull this off with async fn sugar. Suggestions welcome.
Self must not be captured by the future for this to work.
```rust
use potential::Potential;
use std::sync::Arc;
use std::future::Future;
#[derive(Default)]
struct Trial {
    inner: Arc<Potential<String>>
}
impl Trial {
    fn back_to_the_static_future(&self, item:String) -> Box<dyn Future<Output = usize> + 'static + Send + Sync> {
        let inner = self.inner.clone();
        let fut = async move {
            let mut lease = match inner.lease_on_arc().await {
                Ok(lease) => lease,
                Err(gone) => gone.set(String::new())
            };
            // here some other async work...
            lease.extend(item.chars());
            lease.len()
        };
        Box::new(fut)
    }
}
let trial = Trial::default();
let fut = trial.back_to_the_static_future("now".to_owned());
is_sync_and_send_and_static(fut);
fn is_sync_and_send_and_static<T: Sync + Send + 'static>(_: T) {};
```

## License
MIT OR Apache-2.0

### Contribution
Unless you explicitly state otherwise, any contribution 
submitted for inclusion in samotop projects by you, 
as defined in the Apache-2.0 license, shall be licensed 
as above, without any additional terms or conditions.