This manual page is for Mac OS X version 10.6.3

Reading manual pages

transfer::copy::queue(n)                  Data transfer facilities                  transfer::copy::queue(n)



____________________________________________________________________________________________________________

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.1?

       package require transfer::copy::queue  ?0.1?

       transfer::copy::queue object outchannel ?options...?

       object destroy

       object busy

       object pending

       object put request

____________________________________________________________________________________________________________

DESCRIPTION
       This  package  provides  objects which serialize transfer requests for a single channel by means of a
       fifo queue. Accumulating 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


            {type data options...}


       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
       transfer::copy::queue object outchannel ?options...?
              This command creates a new queue object for the management  of  the  channel  outchannel.  The
              fully qualified name of the object command is returned as the result of the command.

              The  only  option  known is -on-status-change. It is optional and defaults to empty, disabling
              the reporting of status changes. Otherwise it argument is  command  prefix  which  is  invoked
              whenever  the  internal  status  of the object changed. The callback is invoked with two addi-tional additional
              tional 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.

       object 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  struc-tures structures
              tures of the destroyed object.

       object 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).

       object 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.

       object 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.


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://source-
       forge.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

COPYRIGHT
       Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>




transfer                                             0.1                            transfer::copy::queue(n)