* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
/**
* This Class pools on an As-Needed-Basis any particular kind of class, which is
* quite suitable for expensive operations.
/**
* This Class pools on an As-Needed-Basis any particular kind of class, which is
* quite suitable for expensive operations.
* The user calls "get" on a Pool, and if a waiting resource (T) is available,
* it will be returned. Otherwise, one will be created with the "Creator" class
* (must be defined for (T)).
* The user calls "get" on a Pool, and if a waiting resource (T) is available,
* it will be returned. Otherwise, one will be created with the "Creator" class
* (must be defined for (T)).
* The returned "Pooled" object simply has to call "done()" and the object is
* returned to the pool. If the developer does not return the object, a memory
* leak does not occur. There are no references to the object once "get" is
* called. However, the developer who does not return the object when done
* obviates the point of the pool, as new Objects are created in place of the
* Object not returned when another call to "get" is made.
* The returned "Pooled" object simply has to call "done()" and the object is
* returned to the pool. If the developer does not return the object, a memory
* leak does not occur. There are no references to the object once "get" is
* called. However, the developer who does not return the object when done
* obviates the point of the pool, as new Objects are created in place of the
* Object not returned when another call to "get" is made.
* There is a cushion of extra objects, currently defaulted to MAX_RANGE. If the
* items returned become higher than the MAX_RANGE, the object is allowed to go
* out of scope, and be cleaned up. the default can be changed on a per-pool
* basis.
* There is a cushion of extra objects, currently defaulted to MAX_RANGE. If the
* items returned become higher than the MAX_RANGE, the object is allowed to go
* out of scope, and be cleaned up. the default can be changed on a per-pool
* basis.
* NOTE TO MAINTAINERS: THIS OBJECT DOES IT'S OWN SYNCHRONIZATION. All
* changes that touch list must account for correctly synchronizing list.
*/
* NOTE TO MAINTAINERS: THIS OBJECT DOES IT'S OWN SYNCHRONIZATION. All
* changes that touch list must account for correctly synchronizing list.
*/
/**
* Create a new Pool, given the implementation of Creator<T>, which must be
* able to create/destroy T objects at will.
/**
* Create a new Pool, given the implementation of Creator<T>, which must be
* able to create/destroy T objects at will.
/**
* Preallocate a certain number of T Objects. Useful for services so that
* the first transactions don't get hit with all the Object creation costs
/**
* Preallocate a certain number of T Objects. Useful for services so that
* the first transactions don't get hit with all the Object creation costs
* This is the essential function for Pool. Get an Object "T" inside a
* "Pooled<T>" object. If there is a spare Object, then use it. If not, then
* create and pass back.
* This is the essential function for Pool. Get an Object "T" inside a
* "Pooled<T>" object. If there is a spare Object, then use it. If not, then
* create and pass back.
* IMPORTANT: When the use of this object is done (and the object is still
* in a valid state), then "done()" should be called immediately to allow
* the object to be reused. That is the point of the Pool...
* IMPORTANT: When the use of this object is done (and the object is still
* in a valid state), then "done()" should be called immediately to allow
* the object to be reused. That is the point of the Pool...
* If the Object is in an invalid state, then "toss()" should be used so the
* Pool doesn't pass on invalid objects to others.
* If the Object is in an invalid state, then "toss()" should be used so the
* Pool doesn't pass on invalid objects to others.
* state. If not, they are tossed from the Pool. This is valuable to have
* when Remote Connections go down, and there is a question on whether the
* Pooled Objects are still functional.
* state. If not, they are tossed from the Pool. This is valuable to have
* when Remote Connections go down, and there is a question on whether the
* Pooled Objects are still functional.
* The Pooled<T> class "offers" it's Object back after use. It is an
* "offer", because Pool will simply destroy and remove the object if it has
* more than enough spares.
* The Pooled<T> class "offers" it's Object back after use. It is an
* "offer", because Pool will simply destroy and remove the object if it has
* more than enough spares.
* The Creator Interface give the Pool the ability to Create, Destroy and
* Validate the Objects it is maintaining. Thus, it is a specially written
* Implementation for each type.
* The Creator Interface give the Pool the ability to Create, Destroy and
* Validate the Objects it is maintaining. Thus, it is a specially written
* Implementation for each type.
* The "Pooled<T>" class is the transient class that wraps the actual Object
* T for API use/ It gives the ability to return ("done()", or "toss()") the
* Object to the Pool when processing is finished.
* The "Pooled<T>" class is the transient class that wraps the actual Object
* T for API use/ It gives the ability to return ("done()", or "toss()") the
* Object to the Pool when processing is finished.
* For Safety, i.e. to avoid memory leaks and invalid Object States, there
* is a "finalize" method. It is strictly for when coder forgets to return
* the object, or perhaps hasn't covered the case during Exceptions or
* For Safety, i.e. to avoid memory leaks and invalid Object States, there
* is a "finalize" method. It is strictly for when coder forgets to return
* the object, or perhaps hasn't covered the case during Exceptions or
* However, we don't want Coding Mistakes to put the whole program in an
* invalid state, so if something happened such that "done()" or "toss()"
* were not called, the resource is still cleaned up as well as possible.
* However, we don't want Coding Mistakes to put the whole program in an
* invalid state, so if something happened such that "done()" or "toss()"
* were not called, the resource is still cleaned up as well as possible.
/**
* This is the key API for the Pool, as calling "done()" offers this
* object back to the Pool for reuse.
/**
* This is the key API for the Pool, as calling "done()" offers this
* object back to the Pool for reuse.
* The user of the Object may discover that the Object t is no longer in
* a valid state. Don't put Garbage back in the Refrigerator... Toss it,
* if it's no longer valid.
* The user of the Object may discover that the Object t is no longer in
* a valid state. Don't put Garbage back in the Refrigerator... Toss it,
* if it's no longer valid.