1transfer::copy::queue(n)   Data transfer facilities   transfer::copy::queue(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       transfer::copy::queue - Queued transfers
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require snit  ?1.0?
14
15       package require struct::queue  ?1.4?
16
17       package require transfer::copy  ?0.2?
18
19       package require transfer::copy::queue  ?0.1?
20
21       transfer::copy::queue objectName outchannel ?options...?
22
23       objectName method ?arg arg ...?
24
25       objectName destroy
26
27       objectName busy
28
29       objectName pending
30
31       objectName put request
32
33______________________________________________________________________________
34

DESCRIPTION

36       This  package  provides objects which serialize transfer requests for a
37       single channel by means of a fifo queue. Accumulated requests are  exe‐
38       cuted  in  order  of  entrance, with the first request reaching an idle
39       object starting the execution in general. New  requests  can  be  added
40       while  the  object is active and are defered until all requests entered
41       before them have been completed successfully.
42
43       When a request causes a transfer error execution stops and all requests
44       coming after it are not served. Currently this means that their comple‐
45       tion callbacks are never triggered at all.
46
47       NOTE: Not triggering the completion callbacks of the unserved  requests
48       after  an error stops the queue object is something I am not fully sure
49       that it makes sense. It forces the user of the queue  to  remember  the
50       callbacks  as  well  and  run them. Because otherwise everything in the
51       system which depends on getting a notification about the  status  of  a
52       request  will hang in the air. I am slowly convincing myself that it is
53       more sensible to trigger the  relevant  completion  callbacks  with  an
54       error message about the queue abort, and 0 bytes transfered.
55
56       All transfer requests are of the form
57
58                {type data options...}
59
60
61       where  type is in {chan, string}, and data specifies the information to
62       transfer.  For chan the data is the handle of  the  channel  containing
63       the  actual  information  to transfer, whereas for string data contains
64       directly the information to transfer.  The options are a list  of  them
65       and  their  values,  and  are the same as are accepted by the low-level
66       copy operations of the package transfer::copy.  Note how just  prepend‐
67       ing  the request with transfer::copy::do and inserting a channel handle
68       in between data and options easily  transforms  it  from  a  pure  data
69       structure into a command whose evaluation will perform the request.
70

API

72   PACKAGE COMMANDS
73       transfer::copy::queue objectName outchannel ?options...?
74              This  command  creates  a new queue object for the management of
75              the channel outchannel, with an  associated  Tcl  command  whose
76              name  is  objectName.   This object command is explained in full
77              detail in the sections Object command and  Object  methods.  The
78              set of supported options is explained in section Options.
79
80              The  object  command will be created under the current namespace
81              if the objectName is not fully qualified, and in  the  specified
82              namespace  otherwise.   The  fully  qualified name of the object
83              command is returned as the result of the command.
84
85   OBJECT COMMAND
86       All objects created by the  ::transfer::copy::queue  command  have  the
87       following general form:
88
89       objectName method ?arg arg ...?
90              The  method method and its arg'uments determine the exact behav‐
91              ior of the command.  See section Object methods for the detailed
92              specifications.
93
94   OBJECT METHODS
95       objectName destroy
96              This  method  destroys  the object. Doing so while the object is
97              busy will cause errors later on,  when  the  currently  executed
98              request  completes  and  tries  to  access  the now missing data
99              structures of the destroyed object.
100
101       objectName busy
102              This method returns a boolean value telling us if the object  is
103              currently  serving  a  request  (i.e.  busy, value True), or not
104              (i.e. idle, value False).
105
106       objectName pending
107              This method returns the number of requests currently waiting  in
108              the queue for their execution. A request currently served is not
109              counted as waiting.
110
111       objectName put request
112              This method enters the transfer request into the object's  queue
113              of waiting requests.  If the object is idle it will become busy,
114              immediately servicing the request. Otherwise servicing  the  new
115              request  will  be defered until all preceding requests have been
116              served.
117

OPTIONS

119       The only option known is -on-status-change. It is optional and defaults
120       to the empty list, disabling the reporting of status changes. Otherwise
121       its argument is a command prefix which is invoked whenever the internal
122       status  of  the  object changed. The callback is invoked with two addi‐
123       tional arguments, the result of the methods pending and busy,  in  this
124       order.  This  allows  any  user  to  easily know, for example, when the
125       object has processed all outstanding requests.
126

USE

128       A possible application of this package and class is within a  HTTP  1.1
129       server, managing the results waiting for transfer to the client.
130
131       It  should  be  noted that in this application the system also needs an
132       additional data structure which keeps track of outstanding  results  as
133       they  may  come  back  in  a different order than the requests from the
134       client, and releases them to the actual queue in the proper order.
135

BUGS, IDEAS, FEEDBACK

137       This document, and the package it describes, will  undoubtedly  contain
138       bugs  and  other problems.  Please report such in the category transfer
139       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
140       also  report any ideas for enhancements you may have for either package
141       and/or documentation.
142
143       When proposing code changes, please provide unified diffs, i.e the out‐
144       put of diff -u.
145
146       Note  further  that  attachments  are  strongly  preferred over inlined
147       patches. Attachments can be made by going  to  the  Edit  form  of  the
148       ticket  immediately  after  its  creation, and then using the left-most
149       button in the secondary navigation bar.
150

KEYWORDS

152       channel, copy, queue, transfer
153

CATEGORY

155       Transfer module
156
158       Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>
159
160
161
162
163tcllib                                0.1             transfer::copy::queue(n)
Impressum