1coroutine(n)                  Coroutine utilities                 coroutine(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       coroutine - Coroutine based event and IO handling
9

SYNOPSIS

11       package require Tcl  8.6
12
13       package require coroutine  1.2
14
15       coroutine::util after delay
16
17       coroutine::util await varname...
18
19       coroutine::util create arg...
20
21       coroutine::util exit ?status?
22
23       coroutine::util gets chan ?varname?
24
25       coroutine::util gets_safety chan limit varname
26
27       coroutine::util global varname...
28
29       coroutine::util read -nonewline chan ?n?
30
31       coroutine::util update ?idletasks?
32
33       coroutine::util vwait varname
34
35______________________________________________________________________________
36

DESCRIPTION

38       The coroutine package provides coroutine-aware implementations of vari‐
39       ous event- and channel related commands. It can be in multiple modes:
40
41       [1]    Call the commands through  their  ensemble,  in  code  which  is
42              explicitly written for use within coroutines.
43
44       [2]    Import  the  commands  into  a  namespace,  either  directly, or
45              through namespace path. This allows the  use  from  within  code
46              which  is  not coroutine-aware per se and restricted to specific
47              namespaces.
48
49       A more agressive form of making code coroutine-oblivious than  point  2
50       above  is  available  through the package coroutine::auto, which inter‐
51       cepts the relevant builtin commands and  changes  their  implementation
52       dependending on the context they are run in, i.e.  inside or outside of
53       a coroutine.
54

API

56       All the commands listed below  are  synchronous  with  respect  to  the
57       coroutine invoking them, i.e. this coroutine blocks until the result is
58       available. The overall eventloop is not blocked however.
59
60       coroutine::util after delay
61              This command delays the coroutine invoking it by delay millisec‐
62              onds.
63
64       coroutine::util await varname...
65              This  command  is an extension form of the coroutine::util vwait
66              command (see below) which waits on a write to one of many  named
67              namespace variables.
68
69       coroutine::util create arg...
70              This  command  creates  a  new  coroutine  with an automatically
71              assigned name and causes it to run the  code  specified  by  the
72              arguments.
73
74       coroutine::util exit ?status?
75              This  command  exits the current coroutine, causing it to return
76              status. If no status was specified the default 0 is returned.
77
78       coroutine::util gets chan ?varname?
79              This command reads a line from the channel chan and  returns  it
80              either  as its result, or, if a varname was specified, writes it
81              to the named variable and returns the number of characters read.
82
83       coroutine::util gets_safety chan limit varname
84              This command reads a line from the channel chan up to size limit
85              and stores the result in varname. Of limit is reached before the
86              set first newline, an error is thrown. The command  returns  the
87              number of characters read.
88
89       coroutine::util global varname...
90              This command imports the named global variables of the coroutine
91              into the current scope. From the technical point of  view  these
92              variables  reside  in  level #1 of the Tcl stack. I.e. these are
93              not the regular global variable in to the global namespace,  and
94              each  coroutine  can have their own set, independent of all oth‐
95              ers.
96
97       coroutine::util read -nonewline chan ?n?
98              This command reads  n  characters  from  the  channel  chan  and
99              returns  them  as  its result. If n is not specified the command
100              will read the channel until EOF is reached.
101
102       coroutine::util update ?idletasks?
103              This command causes the coroutine invoking  it  to  run  pending
104              events or idle handlers before proceeding.
105
106       coroutine::util vwait varname
107              This command causes the coroutine calling it to wait for a write
108              to the named namespace variable varname.
109

BUGS, IDEAS, FEEDBACK

111       This document, and the package it describes, will  undoubtedly  contain
112       bugs  and other problems.  Please report such in the category coroutine
113       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
114       also  report any ideas for enhancements you may have for either package
115       and/or documentation.
116
117       When proposing code changes, please provide unified diffs, i.e the out‐
118       put of diff -u.
119
120       Note  further  that  attachments  are  strongly  preferred over inlined
121       patches. Attachments can be made by going  to  the  Edit  form  of  the
122       ticket  immediately  after  its  creation, and then using the left-most
123       button in the secondary navigation bar.
124

KEYWORDS

126       after, channel, coroutine, events, exit, gets, global,  green  threads,
127       read, threads, update, vwait
128

CATEGORY

130       Coroutine
131

COPYRIGHT

133       Copyright (c) 2010-2015 Andreas Kupries <andreas_kupries@users.sourceforge.net>
134
135
136
137
138tcllib                                1.2                         coroutine(n)