struct::pool(3tcl)

📦
version 2.0 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ struct::pool — the manual, but make it cute ✨

okay bestie, so this is the struct::pool page from the Tcl Data Structures manual, section 3tcl. it's a long one so buckle up 🎀

💖 NAME 💖

struct::pool — create and manipulate pool objects (of discrete items). yes, like a literal pool, but for items. iconic.

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require struct::pool ?1.2.4?

::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 🦋

so this package hands you pool objects, and a pool object is basically a way to manage a finite collection of discrete items. like, you have this limited pile of stuff and you need to keep track of who's using what. very main character of it tbh.

✨ ::struct::pool ?poolName? ?maxsize? ✨

Creates a new pool object. no cap.

  • if you don't pass a poolName, the new pool gets named poolX, where X is a positive integer. so like, it just picks a name for you 💅
  • the optional second argument maxsize has to be a positive integer, and it's the maximum size of the pool — meaning the max 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 is how you invoke all your various configuration operations on the report. it has this general form:

poolName option ?arg arg ...?

where option and the args determine the exact behavior of the command. see the section POOL OBJECT COMMAND for the full detailed list of options and their behaviour. i got you 🫶

🎀 POOLS AND ALLOCATION 🎀

the whole point of the pool command (and the pool object command it generates) is to manage pools of discrete items. examples of a pool of discrete items are, and i quote:

  • 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 all of these is that there's 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. here's the tea:

  • 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 stays constant.

keeping track of which items are allocated, and by whom, is literally the entire purpose of the pool command and its subordinates. that's the job. periodt.

🧚 Pool parlance 🧚

okay vocabulary time, iykyk:

  • if we say an item is allocated, it means 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. and finally, there are even pools from which nothing is ever allocated or returned, like a swimming pool or a cesspool. 💀 yes they really wrote that.

💫 Unique item names

a pool cannot manage duplicate item names. therefore, items in a pool must have unique names. no two same-name besties allowed.

💫 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. so like, the pool doesn't care, but you might 👀

💫 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 most likely results 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. the pool is not your notes app, bestie.

👑 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. and if one or more of the items already exist in the pool, that's also considered an error. so, don't do that 🙈

⭐ 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's supplied on the command line, the pool will be cleared regardless of 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's supplied on the command line, the pool data structure will be destroyed regardless of the allocation state of its items. bye bestie 💀

⭐ 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 type allocID 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. you can't release something that was never held, bestie.

⭐ 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's supplied on the command line, the item will be removed regardless of 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:

  1. 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.
  2. 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).

okay and that's only part one, bestie — there's more coming so don't go anywhere 🌸

🌸 EXAMPLES 🌸

okay bestie, so there's two whole examples here. The first one is a step-by-step interactive tclsh session where every single step gets explained (iconic, honestly), and the second one shows how you'd use this in a server application that talks to a back-end application. 💖

✨ Example 1 ✨

This one is an interactive tclsh session and it's giving Car rental agency. There are ten steps, explained in chronological order — from creating the pool, through the most important stages of using a pool, all the way to the final destruction. A whole character arc fr fr. 😭

Note aside: In this example, brand names are used to label the various items. But heads up — a brand name could be regarded as a property of an item. And because the pool command is not designed to manage properties of items, you'd need to manage those separately. In that latter case, you should label the items with more neutral names like car1, car2, car3, etc... and keep a separate database or array holding the brand names associated with the car labels. 🫶
  1. Load the package into an interpreter
% package require pool
0.1
  1. Create a pool object called CarPool with a maximum size of 55 items (cars):
% pool CarPool 55
CarPool
  1. Add items to the pool:
% CarPool add Toyota Trabant Chrysler1 Chrysler2 Volkswagen
  1. Somebody crashed the Toyota. Remove it from the pool as follows:
% CarPool remove Toyota
  1. Acquired a new car for the pool. Add it as follows:
% CarPool add Nissan
  1. 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:

  1. When the car is returned then you can render it available by:
% CarPool release Trabant
  1. 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. 😭

  1. 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's a server application that receives requests from client applications, and those client requests get 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 that a client request may be passed along to. The file descriptors that identify the channels to these back-end instances make up a pool of connections. And a particular connection may be allocated to just one client request at a time. no cap 💅

# 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.
}

🐛 BUGS, IDEAS, FEEDBACK 🐛

ngl, this document, and the package it describes, will undoubtedly contain bugs and other problems. Bestie, please report such in the category struct :: pool of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. 🙈

Please also report any ideas for enhancements you may have for either the package and/or the documentation. We want the glow-up. ✨

When proposing code changes, please provide unified diffs, i.e. the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. iykyk 🫶

👑 KEYWORDS 👑

discrete items, finite, pool, struct

🌈 CATEGORY 🌈

Data structures

Copyright (c) 2002, Erik Leunissen <e.leunissen@hccnet.nl>

okay that's the whole page bestie, we ate and left no crumbs 💅 this was tcllib version 1.2.4, page struct::pool(3tcl) — periodt, go build something iconic with it 🎀🦋💖

📦 where this page comes from