Pond

Pond is a high performance object-pooling library for Python, it has a smaller memory usage and a higher borrow hit rate. For more details, see our user's guide or my blog(https://qin.news).

English | 中文版

Pond is probably the first publicly available object pooling library in Python with complete test cases, over 90% coverage, complete code comments, and good documentation.

Inspired by Apache Commons Pool, Netty Recycler, HikariCP, Caffeine. Pond counts the frequency of usage of each object pool using approximate counting with extremely little memory usage, and recycles it automatically.

The default policy and weights reduce the memory usage by 48.85% and the borrow hit rate at 100% when the traffic is more randomly averaged.

The default policy and weights reduce the memory usage by 45.7% and the borrow hit rate at 100% when the traffic is more in line with the 2/8 law.

Overview

Using Pond requires the implementation of an object factory, PooledObjectFactory, which provides object creation, initialization, destruction, validation, and other operations called by Pond. So in order for the object pool to support holding completely different objects, Pond uses a dictionary to save the name of each factory class and the instantiated objects of the factory class it implements.

Ponds are thread-safe and coroutine-safe for borrowing and recycling, and Python's queue module provides a first-in, first-out (FIFO) data structure for multi-threaded programming. It can be used to safely pass messages or other data between producer and consumer threads. Locks are handled by the caller, and all multiple threads can safely and easily work with the same Queue instance. The borrowing and recycling of a Pond is all about manipulating the queue, so it is basically considered thread-safe.

The auto-recycle is executed at regular intervals, 300s by default. Automatically cleans up the objects in the infrequently used object pool.

It is recommended that you use Python 3.8 or greater.

User guide

To install Pond via pip, use the following pip command:

pip install pondpond

from pond import Pond, PooledObjectFactory, PooledObject

First you need to declare a factory class for the type of object you want to put in. For example, in the example below we want the pooled object to be Dog, so we first declare a PooledDogFactory class and implement PooledObjectFactory.

class Dog:
    name: str
    validate_result:bool = True


class PooledDogFactory(PooledObjectFactory):
    def createInstance(self) -> PooledObject:
        dog = Dog()
        dog.name = "puppy"
        return PooledObject(dog)

    def destroy(self, pooled_object: PooledObject):
        del pooled_object

    def reset(self, pooled_object: PooledObject) -> PooledObject:
        pooled_object.keeped_object.name = "puppy"
        return pooled_object

    def validate(self, pooled_object: PooledObject) -> bool:
        return pooled_object.keeped_object.validate_result

You need creat a new instance of Pond：

pond = Pond(borrowed_timeout=2,
            time_between_eviction_runs=-1,
            thread_daemon=True,
            eviction_weight=0.8)

Pond can be passed a number of parameters in:

borrowed_timeout: The maximum duration of the borrowed object. Defaults to 60.

time_between_eviction_runs: The interval for automatic recycling. Defaults to 300. If its value is -1, the recycling is turned off.

thread_daemon: A boolean value indicating whether the pond's thread is a daemon thread. Defaults to True.

eviction_weight: Automatic recycling weight. Defaults to 0.8.

loop: Automatic recycling weight. Defaults to 0.8.

Creat a new instance of your custom class of fatory：

factory = PooledDogFactory(pooled_maxsize=10, least_one=False)

pooled_maxsize: The maximum number of objects that can be placed in the object pool of the objects generated by this factory class.

least_one: If True, the object pool of objects generated by this factory class will retain at least one object when it enters auto-recycle.

Register the factory object with Pond; by default, the class name of the factory class is used as the PooledObjectTree's key.

pond.register(factory)

Of course you can also customize its name：

pond.register(factory, name="PuppyFactory")

If the register succeeds, the Pond will begin creating objects based on the pooled_maxsize set in the factory until the pool is full.

Borrow and recycle object(You can also use coroutine function with coroutine locks):

pooled_object: PooledObject = pond.borrow(factory)
# or
pooled_object: PooledObject = pond.async_borrow(factory)
dog: Dog = pooled_object.use()
pond.recycle(pooled_object, factory)
# or
pond.async_recycle(pooled_object, factory)

Borrow and recycle object by name:

pooled_object: PooledObject = pond.borrow(name="PuppyFactory")
dog: Dog = pooled_object.use()
pond.recycle(pooled_object, name="PuppyFactory")

The 1.4.1 version supports returning custom parameters that can be passed to the reset method of the factory class:

class PooledDogFactory(PooledObjectFactory):
    ...
    def reset(self, pooled_object: PooledObject, new_name) -> PooledObject:
        pooled_object.keeped_object.name = new_name
        return pooled_object

pond.recycle(pooled_object, factory, new_name="kiki")

Clear a object pool:

pond.clear(factory)
# or
pond.async_clear(factory)

Clear a object pool by name:

pond.clear(name="PuppyFactory")

More Details

For more details, see our user's guide or my blog（https://qin.news）.

References

@software{Pond,
  author = {Andy Qin},
  title = {{Pond: A high performance object-pooling library for Python}},
  year = {2022},
  url = {https://github.com/T-baby/pondpond},
}