|
ActiveTcl User Guide
|
|
|
pool(n) 1.2.1 struct "Tcl Data Structures"
NAME
pool - Create and manipulate pool objects (of discrete
items)
SYNOPSIS
package require Tcl 8.2
package require struct ?1.2.1?
::struct::pool ?poolName?
?maxsize? |
poolName option ?arg arg ...? |
poolName add itemName1 ?itemName2 itemName3
...? |
poolName clear
?-force? |
poolName destroy
?-force? |
poolName info type ?arg? |
poolName maxsize ?maxsize? |
poolName release itemName |
poolName remove itemName ?-force? |
poolName request itemVar
?options? |
|
DESCRIPTION
This package provides pool objects which can be used to manage
finite collections of discrete items.
- ::struct::pool ?poolName?
?maxsize?
- Creates a new pool object. If no poolName is
supplied, then the new pool will be named poolX,
where X is a positive integer. The optional second argument maxsize has to be a positive integer indicating the
maximum size of the pool; this is the maximum number of items the
pool may hold. The default for this value is
10.
The pool object has an associated global Tcl command whose name is
poolName. This command may be used to invoke
various configuration operations on the report. It has the
following general form:
- poolName option ?arg arg ...?
- Option and the args
determine the exact behavior of the command. See section POOL OBJECT COMMAND for a detailed list of
options and their behaviour.
POOLS AND ALLOCATION
The purpose of the pool command and the pool object command that it
generates, is to manage pools of discrete items. Examples of a pool
of discrete items are:
- the seats in a cinema, theatre, train etc.. for which
visitors/travelers can make a reservation;
- the dynamic IP-addresses that an ISP can dole out to
subscribers;
- a car rental's collection of cars, which can be rented by
customers;
- the class rooms in a school building, which need to be
scheduled;
- the database connections available to client-threads in a
web-server application;
- the books in a library that customers can borrow;
- etc ...
The common denominator in the examples is that there is a more
or less fixed number of items (seats, IP-addresses, cars, ...) that
are supposed to be allocated on a more or less regular basis. An
item can be allocated only once at a time. An item that is
allocated, must be released before it can be re-allocated. While
several items in a pool are being allocated and released
continuously, the total number of items in the pool remains
constant.
Keeping track of which items are allocated, and by whom, is the
purpose of the pool command and its subordinates.
Pool parlance: If we say that an item is
allocated, it means that the item is
busy, owned or
occupied; it is not available anymore. If an item
is free, it is available.
Deallocating an item is equivalent to setting free or releasing an
item. The person or entity to which the item has been allotted is
said to own the item.
ITEMS
Discrete items
The pool command is designed for
discrete items only. Note that there are pools
where allocation occurs on a non-discrete basis, for example
computer memory. There are also pools from which the shares that
are doled out are not expected to be returned, for example a
charity fund or a pan of soup from which you may receive a portion.
Finally, there are even pools from which nothing is ever allocated
or returned, like a swimming pool or a cesspool.
Unique item names
A pool cannot manage duplicate item names. Therefore, items in a
pool must have unique names.
Item equivalence
From the point of view of the manager of a pool, items are
equivalent. The manager of a pool is indifferent about which
entity/person occupies a given item. However, clients may have
preferences for a particular item, based on some item property they
know.
Preferences
A future owner may have a preference for a particular item.
Preference based allocation is supported (see the
-prefer option to the request subcommand). A
preference for a particular item is most likely to result from
variability among features associated with the items. Note that the
pool commands themselves are not designed to manage such item
properties. If item properties play a role in an application, they
should be managed separately.
POOL OBJECT COMMAND
The following subcommands and corresponding arguments are available
to any pool object command.
- poolName add itemName1 ?itemName2 itemName3
...?
- This command adds the items on the command line to the pool. If
duplicate item names occur on the command line, an error is raised.
If one or more of the items already exist in the pool, this also is
considered an error.
- poolName clear
?-force?
- Removes all items from the pool. If there are any allocated
items at the time when the command is invoked, an error is raised.
This behaviour may be modified through the -force
argument. If it is supplied on the command line, the pool will be
cleared regardless the allocation state of its items.
- poolName destroy
?-force?
- Destroys the pool data structure, all associated variables and
the associated pool object command. By default, the command checks
whether any items are still allocated and raises an error if such
is the case. This behaviour may be modified through the argument
-force. If it is supplied on the command line, the
pool data structure will be destroyed regardless allocation state
of its items.
- poolName info type ?arg?
- Returns various information about the pool for further
programmatic use. The type argument indicates
the type of information requested. Only the
allocID type uses an additional argument.
- allocID itemName
- returns the allocID of the item whose name is itemName. Free items have an allocation id of
-1.
- allitems
- returns a list of all items in the pool.
- allocstate
- Returns a list of key-value pairs, where the keys are the items
and the values are the corresponding allocation id's. Free items
have an allocation id of -1.
- cursize
- returns the current pool size, i.e. the number of items in the
pool.
- freeitems
- returns a list of items that currently are not allocated.
- maxsize
- returns the maximum size of the pool.
- poolName maxsize ?maxsize?
- Sets or queries the maximum size of the pool, depending on
whether the maxsize argument is supplied or not.
If maxsize is supplied, the maximum size of the
pool will be set to that value. If no argument is supplied, the
current maximum size of the pool is returned. In this variant, the
command is an alias for:
poolName info maxsize.
The maxsize argument has to be a positive
integer.
- poolName release itemName
- Releases the item whose name is itemName
that was allocated previously. An error is raised if the item was
not allocated at the time when the command was issued.
- poolName remove itemName ?-force?
- Removes the item whose name is itemName from
the pool. If the item was allocated at the time when the command
was invoked, an error is raised. This behaviour may be modified
through the optional argument -force. If it is
supplied on the command line, the item will be removed regardless
its allocation state.
- poolName request itemVar
?options?
- Handles a request for an item, taking into account a possible
preference for a particular item. There are two possible outcomes
depending on the availability of items:
- The request is honoured, an item is allocated and the variable
whose name is passed with the argument itemVar
will be set to the name of the item that was allocated. The command
returns 1.
- The request is denied. No item is allocated. The variable whose
name is itemVar is not set. Attempts to read itemVar may raise an error if the variable was not
defined before issuing the request. The command returns 0.
The return values from this command are meant to be inspected. The
examples below show how to do this. Failure to check the return
value may result in erroneous behaviour. If no preference for a
particular item is supplied through the option
-prefer (see below), then all requests are
honoured as long as items are available.
The following options are supported:
- -allocID allocID
- If the request is honoured, an item will be allocated to the
entity identified by allocID. If the allocation state of an item is
queried, it is this allocation ID that will be returned. If the
option -allocID is not supplied, the item will be
given to and owned by dummyID. Allocation id's may
be anything except the value -1, which is reserved for free
items.
- -prefer preferredItem
- This option modifies the allocation strategy as follows: If the
item whose name is preferredItem is not
allocated at the time when the command is invoked, the request is
honoured (return value is 1). If the item was allocated at the time
when the command was invoked, the request is denied (return value
is 0).
EXAMPLES
Two examples are provided. The first one mimics a step by step
interactive tclsh session, where each step is explained. The second
example shows the usage in a server application that talks to a
back-end application.
Example 1
This example presents an interactive tclsh session which
considers the case of a Car rental's collection of cars. Ten steps
explain its usage in chronological order, from the creation of the
pool, via the most important stages in the usage of a pool, to the
final destruction.
Note aside:
In this example, brand names are used to label the various
items. However, a brand name could be regarded as a property of an
item. Because the pool command is not designed to manage properties
of items, they need to be managed separately. In the latter case
the items should be labeled with more neutral names such as: car1,
car2, car3 , etc ... and a separate database or array should hold
the brand names associated with the car labels.
|
1. Load the package into an interpreter
% package require pool
0.1
2. Create a pool object called `CarPool' with a maximum size of 55 items (cars):
% pool CarPool 55
CarPool
4. Add items to the pool:
% CarPool add Toyota Trabant Chrysler1 Chrysler2 Volkswagen
5. Somebody crashed the Toyota. Remove it from the pool as follows:
% CarPool remove Toyota
6. Acquired a new car for the pool. Add it as follows:
% CarPool add Nissan
7. Check whether the pool was adjusted correctly:
% CarPool info allitems
Trabant Chrysler1 Chrysler2 Volkswagen Nissan
|
Suspend the interactive session temporarily, and show the
programmatic use of the request subcommand:
|
# Mrs. Swift needs a car. She doesn't have a preference for a
# particular car. We'll issue a request on her behalf as follows:
if { [CarPool request car -allocID "Mrs. Swift"] } {
# request was honoured, process the variable `car'
puts "$car has been allocated to [CarPool info allocID $car]."
} else {
# request was denied
puts "No car available."
}
|
Note how the if command uses the value
returned by the request subcommand.
|
# Suppose Mr. Wiggly has a preference for the Trabant:
if { [CarPool request car -allocID "Mr. Wiggly" -prefer Trabant] } {
# request was honoured, process the variable `car'
puts "$car has been allocated to [CarPool info allocID $car]."
} else {
# request was denied
puts "The Trabant was not available."
}
|
Resume the interactive session:
|
8. When the car is returned then you can render it available by:
% CarPool release Trabant
9. When done, you delete the pool.
% CarPool destroy
Couldn't destroy `CarPool' because some items are still allocated.
Oops, forgot that Mrs. Swift still occupies a car.
10. We force the destruction of the pool as follows:
% CarPool destroy -force
|
Example 2
This example describes the case from which the author's need for
pool management originated. It is an example of a server
application that receives requests from client applications. The
client requests are dispatched onto a back-end application before
being returned to the client application. In many cases there are a
few equivalent instances of back-end applications to which a client
request may be passed along. The file descriptors that identify the
channels to these back-end instances make up a pool of connections.
A particular connection may be allocated to just one client request
at a time.
|
# Create the pool of connections (pipes)
set maxpipes 10
pool Pipes $maxpipes
for {set i 0} {$i < $maxpipes} {incr i} {
set fd {open "|backendApplication" w+}
Pipes add $fd
}
# A client request comes in. The request is identified as `clientX'.
# Dispatch it onto an instance of a back-end application
if { [Pipes request fd -allocID clientX] } {
# a connection was allocated
# communicate to the back-end application via the variable `fd'
puts $fd "someInstruction"
# ...... etc.
} else {
# all connections are currently occupied
# store the client request in a queue for later processing,
# or return a 'Server busy' message to the client.
}
|
KEYWORDS
struct, pool, finite, discrete items