{"id":20741193,"url":"https://github.com/bbottema/generic-object-pool","last_synced_at":"2025-04-24T03:07:23.869Z","repository":{"id":50423816,"uuid":"194274587","full_name":"bbottema/generic-object-pool","owner":"bbottema","description":"A flexible thread-safe generic object pool","archived":false,"fork":false,"pushed_at":"2024-09-15T10:04:58.000Z","size":88,"stargazers_count":3,"open_issues_count":2,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-24T03:07:15.443Z","etag":null,"topics":["concurrency","high-performance","java","object-pool","pool"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbottema.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-2.0.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-28T13:00:02.000Z","updated_at":"2024-09-15T10:05:00.000Z","dependencies_parsed_at":"2024-05-14T13:28:06.013Z","dependency_job_id":"a4cef035-73d1-458b-a206-962fe6fc720f","html_url":"https://github.com/bbottema/generic-object-pool","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbottema%2Fgeneric-object-pool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbottema%2Fgeneric-object-pool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbottema%2Fgeneric-object-pool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbottema%2Fgeneric-object-pool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbottema","download_url":"https://codeload.github.com/bbottema/generic-object-pool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250552072,"owners_count":21449164,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["concurrency","high-performance","java","object-pool","pool"],"created_at":"2024-11-17T06:34:47.391Z","updated_at":"2025-04-24T03:07:23.852Z","avatar_url":"https://github.com/bbottema.png","language":"Java","readme":"[![APACHE v2 License](https://img.shields.io/badge/license-apachev2-blue.svg?style=flat)](LICENSE-2.0.txt) \n[![Latest Release](https://img.shields.io/maven-central/v/com.github.bbottema/generic-object-pool.svg?style=flat)](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22com.github.bbottema%22%20AND%20a%3A%22generic-object-pool%22)\n[![Javadocs](https://img.shields.io/badge/javadoc-2.0.0-brightgreen.svg?color=brightgreen)](https://www.javadoc.io/doc/com.github.bbottema/generic-object-pool) \n[![Codacy](https://img.shields.io/codacy/grade/b1183f7def224cd7b505b42a9a1e2b65.svg?style=flat)](https://www.codacy.com/app/b-bottema/generic-object-pool)\n\n# generic-object-pool\n\ngeneric-object-pool is a lightweight generic object pool, providing object lifecycle management, \nmetrics, claim / release mechanism and object invalidation, as well as auto initialize a core pool and \nauto expiry policies.\n\n## Setup\n\nMaven Dependency Setup\n\n```xml\n\u003cdependency\u003e\n\t\u003cgroupId\u003ecom.github.bbottema\u003c/groupId\u003e\n\t\u003cartifactId\u003egeneric-object-pool\u003c/artifactId\u003e\n\t\u003cversion\u003e2.2.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Usage\n\n#### Creating pools\n\n```java\n// basic pool with no eager loading and no expiry policy\nPoolConfig\u003cFoo\u003e poolConfig = PoolConfig.\u003cFoo\u003ebuilder()\n   .maxPoolsize(10)\n   .build();\n\nGenericObjectPool\u003cFoo\u003e pool = new SimpleObjectPool\u003c\u003e(poolConfig, new MyFooAllocator());\n```\n\n```java\n// more advanced pool with eager loading and auto expiry\nPoolConfig\u003cFoo\u003e poolConfig = PoolConfig.\u003cAtomicReference\u003cInteger\u003e\u003ebuilder()\n   .corePoolsize(20) // keeps 20 objects eagerly allocated at all times\n   .maxPoolsize(20)\n   // deallocate after 30 seconds, but every time an object is claimed the expiry timeout is reset\n   .expirationPolicy(new TimeoutSinceLastAllocationExpirationPolicy\u003cFoo\u003e(30, TimeUnit.SECONDS))\n   .build();\n\nGenericObjectPool\u003cFoo\u003e pool = new SimpleObjectPool\u003c\u003e(poolConfig, new MyFooAllocator());\n````\n\n#### Claim / release API\n\nClaiming objects from the pool (blocking):\n```java\n// borrow an object and block until available\nPoolableObject\u003cFoo\u003e obj = pool.claim();\n````\n\nClaiming objects from the pool (blocking until timeout):\n```java\nPoolableObject\u003cFoo\u003e obj = pool.claim(key, 1, TimeUnit.SECONDS); // null if timed out\n````\n\nReleasing Objects back to the Pool:\n```java\nPoolableObject\u003cFoo\u003e obj = pool.claim();\nobj.release(); // make available for reuse\n// or\nobj.invalidate(); // remove from pool, deallocating\n````\n\n#### Shutting down a pool\n\n```java\nFuture\u003c?\u003e shutdownSequence = pool.shutdown();\n\n// wait for shutdown to complete\nshutdownSequence.get();\n// until timeout\nshutdownSequence.get(10, TimeUnit.SECONDS);\n````\n\n#### Creating your objects\n\nImplementing a simple Allocator to create your objects when populating the pool either eagerly or lazily.\nEvery method except `allocate` is optional:\n```java\nstatic class FooAllocator extends Allocator\u003cFoo\u003e {\n\t/**\n\t * Initial creation and initialization.\n\t * Called when claim comes or when pool is eagerly loading for core size.\n\t */\n\t@Override\n\tpublic AtomicReference\u003cInteger\u003e allocate() {\n\t\treturn new Foo();\n\t}\n}\n```\n\nMore comprehensive life cycle management:\n```java\nstatic class FooAllocator extends Allocator\u003cFoo\u003e {\n\t/**\n\t * Initial creation and initialization.\n\t * Called when claim comes or when pool is eagerly loading for core size.\n\t */\n\t@Override\n\tpublic AtomicReference\u003cInteger\u003e allocate() {\n\t\treturn new Foo();\n\t}\n\t\n\t/**\n\t * Uninitialize an instance which has been released back to the pool, until it is claimed again.\n\t */\n\t@Override\n\tprotected void deallocateForReuse(Foo object) {\n\t\tobject.putAtRest();\n\t}\n\t\n\t/**\n\t * Reinitialize an object so it is ready to be claimed.\n\t */\n\t@Override\n\tprotected void allocateForReuse(Foo object) {\n\t\tobject.reinitialize();\n\t}\n\t\n\t/**\n\t * Clean up an object no longer needed by the pool.\n\t */\n\t@Override\n\tprotected void deallocate(Foo object) {\n\t\tobject.clear();\n\t}\n}\n```\n\n#### Metrics\n\n```java\nPoolMetrics metrics = pool.getPoolMetrics();\nmetrics.getCurrentlyClaimed(); // currently claimed by threads and not released yet\nmetrics.getCurrentlyWaitingCount(); // currently waiting threads that want to claim\nmetrics.getCorePoolsize(); // number of instances to auto allocated (eager loading)\nmetrics.getMaxPoolsize(); // max number of objects allowed at all times\nmetrics.getCurrentlyAllocated(); // available + claimed objects\nmetrics.getTotalAllocated(); // total number of allocations during pool's existence\nmetrics.getTotalClaimed(); // total number of claims during pool's existence\n```\n\nIf for some reason you need to have more control over how threads are created, you can provide you own ThreadFactory:\n```java\nPoolConfig\u003cFoo\u003e poolConfig = PoolConfig.\u003cAtomicReference\u003cInteger\u003e\u003ebuilder()\n   .threadFactory(new MyCustomThreadFactory())\n   .build();\n```\n\n#### Other Expiry strategies\n\nYou can expire objects based on age since creation or age since last allocation. For these use:\n* `TimeoutSinceCreationExpirationPolicy`\n* `TimeoutSinceLastAllocationExpirationPolicy`\n\nYou can also spread the expiry around in a bandwidth to avoid having everything expire at the same time, hogging system resources. for these use:\n* `SpreadedTimeoutSinceCreationExpirationPolicy`\n* `SpreadedTimeoutSinceLastAllocationExpirationPolicy`\n\nYou can also combine multiple expirations, by passing instances of them as a set to:\n* `CombinedExpirationPolicies`\n\nFinally, you can extend any of these or create your own from scratch by implementing:\n* `ExpirationPolicy`\n\nTo aid you in creating your own expiry policy, you can calculate and store an expiry age on the poolable object:\n```java\npoolableObject.getExpiries().put(this, calculatedAge);\nLong previouslyCalculateAge = poolableObject.getExpiries().get(this);\n```\nYou can always extend one the abstract classes `SpreadedTimeoutExpirationPolicy` and `TimeoutExpirationPolicy`, which do this for you.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbottema%2Fgeneric-object-pool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbottema%2Fgeneric-object-pool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbottema%2Fgeneric-object-pool/lists"}