pool - Create and manipulate pool objects (of discrete items)
SYNOPSIS
package require Tcl 8.2
package require struct ?1.2.1?
|
This package provides pool objects which can be used to manage finite collections of discrete items.
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.
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.
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 labelled 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.
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:
ITEMS
Discrete items
POOL OBJECT COMMAND
The following subcommands and corresponding arguments are available to
any pool object command.
poolName info maxsize.
The maxsize argument has to be a positive integer.
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:
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.
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. } |