NAME¶
transfer::copy::queue - Queued transfers
SYNOPSIS¶
package require
Tcl 8.4
package require
snit ?1.0?
package require
struct::queue ?1.4?
package require
transfer::copy ?0.2?
package require
transfer::copy::queue ?0.1?
transfer::copy::queue objectName outchannel
?
options...?
objectName method ?
arg arg ...?
objectName destroy
objectName busy
objectName pending
objectName put request
DESCRIPTION¶
This package provides objects which serialize transfer requests for a single
channel by means of a fifo queue. Accumulated requests are executed in order
of entrance, with the first request reaching an idle object starting the
execution in general. New requests can be added while the object is active and
are defered until all requests entered before them have been completed
successfully.
When a request causes a transfer error execution stops and all requests coming
after it are not served. Currently this means that their completion callbacks
are never triggered at all.
NOTE: Not triggering the completion callbacks of the unserved requests
after an error stops the queue object is something I am not fully sure that it
makes sense. It forces the user of the queue to remember the callbacks as well
and run them. Because otherwise everything in the system which depends on
getting a notification about the status of a request will hang in the air. I
am slowly convincing myself that it is more sensible to trigger the relevant
completion callbacks with an error message about the queue abort, and 0 bytes
transfered.
All transfer requests are of the form
where
type is in {
chan,
string}, and
data specifies
the information to transfer. For
chan the data is the handle of the
channel containing the actual information to transfer, whereas for
string data contains directly the information to transfer. The
options are a list of them and their values, and are the same as are
accepted by the low-level copy operations of the package
transfer::copy. Note how just prepending the request with
transfer::copy::do and inserting a channel handle in between
data and
options easily transforms it from a pure data structure
into a command whose evaluation will perform the request.
API¶
PACKAGE COMMANDS¶
- transfer::copy::queue objectName
outchannel ? options...?
- This command creates a new queue object for the management
of the channel outchannel, with an associated Tcl command whose
name is objectName. This object command is explained in full
detail in the sections Object command and Object methods.
The set of supported options is explained in section
Options.
The object command will be created under the current namespace if the
objectName is not fully qualified, and in the specified namespace
otherwise. The fully qualified name of the object command is returned as
the result of the command.
OBJECT COMMAND¶
All objects created by the
::transfer::copy::queue command have the
following general form:
- objectName method ?arg arg ...?
- The method method and its arg'uments
determine the exact behavior of the command. See section Object
methods for the detailed specifications.
OBJECT METHODS¶
- objectName destroy
- This method destroys the object. Doing so while the object
is busy will cause errors later on, when the currently executed request
completes and tries to access the now missing data structures of the
destroyed object.
- objectName busy
- This method returns a boolean value telling us if the
object is currently serving a request (i.e. busy, value
True), or not (i.e. idle, value False).
- objectName pending
- This method returns the number of requests currently
waiting in the queue for their execution. A request currently served is
not counted as waiting.
- objectName put request
- This method enters the transfer request into the
object's queue of waiting requests. If the object is idle it will
become busy, immediately servicing the request. Otherwise servicing
the new request will be defered until all preceding requests have been
served.
OPTIONS¶
The only option known is
-on-status-change. It is optional and defaults
to the empty list, disabling the reporting of status changes. Otherwise its
argument is a command prefix which is invoked whenever the internal status of
the object changed. The callback is invoked with two additional arguments, the
result of the methods
pending and
busy, in this order. This
allows any user to easily know, for example, when the object has processed all
outstanding requests.
USE¶
A possible application of this package and class is within a HTTP 1.1 server,
managing the results waiting for transfer to the client.
It should be noted that in this application the system also needs an additional
data structure which keeps track of outstanding results as they may come back
in a different order than the requests from the client, and releases them to
the actual queue in the proper order.
BUGS, IDEAS, FEEDBACK¶
This document, and the package it describes, will undoubtedly contain bugs and
other problems. Please report such in the category
transfer of the
Tcllib SF Trackers [
http://sourceforge.net/tracker/?group_id=12883].
Please also report any ideas for enhancements you may have for either package
and/or documentation.
KEYWORDS¶
channel, copy, queue, transfer
CATEGORY¶
Transfer module
COPYRIGHT¶
Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>