


transfer::copy::queueData transfer facilitransfer::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.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  exe-
       cuted  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 comple-
       tion 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





transfer                       0.1                              1





transfer::copy::queueData transfer facilitransfer::copy::queue(n)


            {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  prepend-
       ing  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 behav-
              ior 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.



transfer                       0.1                              2





transfer::copy::queueData transfer facilitransfer::copy::queue(n)


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

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

CATEGORY
       Transfer module

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
















transfer                       0.1                              3


