Use something like this crate to help the compiler optimize away bits like:

   fn as_ref(&self) -> &T {
    match self.value.as_ref() {
      Some(v) => v,
      // This is unreachable but is currently preserved by LLVM
      None => panic!("Recycled<T> smartpointer missing its value.")
    }
  }

There may be other reasons to walk the values Vec so perhaps this should be generic. This is useful if the Pool contains sockets(TCP) where periodic pings need to be replied to, but I can think of other reasons.

Attached values that are going out of scope should drop altogether instead of being added back into the pool.

Helpful for buffers. Presently the value type has to have a starting size baked into its constructor.

Thanks to @Marwes, users can now choose between issued values being governed by & or Rc. We should show the benchmarks for both.

Pools come with a few options:

• starting size
• maximum size
• an initialization reference value

This has caused a variety of constructors to pop up:

• with_size
• with_size_and_max
• with_size_and_max_from

This should be exposed via a builder for simplicity. Something like:

let string_pool: Pool<String> = Pool::new()
  .with(StartingSize(15))
  .with(MaximumSize(100))
  .with(InitializationReference(my_value))
  .build();

Vec::with_capacity takes a usize. We should follow suit.

At present the only documentation are the examples in the README. Add rustdoc comments and host the generated docs somewhere.

Pool values are currently neither Send nor Sync, which precludes some interesting use cases around rayon and crossbeam.

Add support for creating a Pool that emits Arc references once Generic Associated Types (rust-lang/rust/issues/44265) lands.

The Drop implementation for the RecycledInner type is responsible for returning the value being dropped to the Pool that originally issued it.

The insert_or_drop method performs two operations:

1. If the CappedCollection has available capacity, the provided value will be reset() and then added to the Pool again.
2. If it does not have capacity, the value will be drop()ed.

If the value contains other values from the same Pool (e.g. it's a nested container, like a Vec that indirectly contains other Vecs), the call to reset() in step 1 will cause the program to panic!(). This happens because the call to insert_or_drop uses a mutable borrow of the RefCell<CappedCollection<_>>. A nested call to insert_or_drop will also try to mutably borrow the RefCell<CappedCollection<_>>, causing RefCell's runtime validation logic to panic!().

This can be fixed by refactoring the Drop implementation to:

• Immutably borrow the RefCell<CappedCollection<_>> to test its available capacity.
  • If there's no space available, drop the value.
  • If there is space available, call reset() on the value being returned to the Pool. (Notice that we're now resetting it without holding a mutable reference to the RefCell<CappedCollection<_>>.) Then mutably borrow the collection and add the value to it.

The detach() method on Recycled values is the only way that the Option<T> it contains can be emptied prior to drop being called. drop currently branches to handle the empty case. If detach is removed (or re-designed), the branch can be removed. This would optimize drop, which happens for all Recycled values eventually, instead of detach, which only happens if requested.

Here, this crate causes UB by "Producing an invalid value". Concretely, it produces a value of an arbitrary type T with mem::uninitialized(). In the near future the call to mem::uninitialized() will panic to avoid UB, and our crater run determined that this crate will be affected.

mem::uninitialized() is deprecated since Rust 1.39. The intended replacement is MaybeUninit, which tracks the possibility of uninitialized values at the type level to make sure the compiler does not make any false assumptions. I see you are using ManuallyDrop; likely the fix will involve replacing that by MaybeUninit.

Because RcRecycled values hold an Rc reference to the Pool, the only way to free the memory used by the Pool is to drop the Pool and all of the references it has passed out.

If the Pool has gone out of scope, it can no longer be used to retrieve value instances. This means there is no value in keeping it on the heap so Recycled values can be returned to it -- we may as well drop() those values where they are.

We should replace the current Rc pointer with a Weak pointer so the Pool's lifetime is not unnecessarily extended by outstanding references. This will add a small amount of overhead to the Drop and detach() implementations, but is worth it to avoid unexpected memory overhead.

I love the library!

I've tossed around a similar idea for artifact, and actually implemented it but didn't find much performance benefit. Maybe you can improve on my idea...

My application used a fair amount of Arc data types, but many of them were constructed from the user. Because of this, items that could simply be a pointer to an existing Arc end up being allocated anyway.

I'm not sure if lifeguard could offer an API for this, but I figured it was worth mentioning. I think keeping lifeguard as-is (as a focused library) is probably preferred, but thought you might find the idea intriguing 😄

Supplier is used to construct new instances, however the user may also want to control the maximum size allowed when items go back into the pool to avoid OOM.

I recommend the name Recycler, although you can use whatever name you think is fitting.

use case:

extern crate lifeguard;
use lifeguard::*;

fn main() {
 let pool : Pool<String> = pool()
   // The pool will allocate 128 values for immediate use. More will be allocated on demand.
   .with(StartingSize(128))
   // The pool will only grow up to 4096 values. Further values will be dropped.
   .with(MaxSize(4096))
   // The pool will use this closure (or other object implementing Supply<T>) to allocate
   .with(Supplier(|| String::with_capacity(1024)))
   // The pool will use this closure when adding recycled items back to the pool
   .with(Recycler(|s| {
        s.clear()
        // nightly only
        if s.capacity() > 4096 {
            s.shrink_to(4096); 
        }
    })
   .build();
  // ...
}

Deref and DerefMut can probably be defined in terms of AsRef and AsMut.

We can eliminate the overhead of constantly having to check whether the contained value has been detach()ed by:

• Wrapping it in ManuallyDrop instead of Option
• Modifying detach() to completely deconstruct the value without relying on Drop being called later.

As seen in #11, this will grant a modest speed increase without hurting ergonomics.

Currently, Recycled doesn't forward very many traits, even if the underlying type implements them. In particular, fairly standard traits such as Clone, PartialOrd or Hash are inaccessible through Recycled and RcRecycled. This makes the wrapper type much harder to work with, and is pretty easy to fix. The impls section of Rc provides a fairly good list of traits that it's good for wrapper types to proxy.

Also rename benchmarks to avoid the need for numbering.