@@ 63,75 63,83 @@ irc wrapper.
Configure listener-type event handlers.
-Listener-type handlers are scripts, executed in a sub-interpreter.
-The script is executed as part of event handling, and is expected to
-return to the main interpreter via **`after`** periodically. For
-application responsiveness and stability reasons, it is expected that
-listener scripts will not take longer than 100ms to execute, though
-this is not enforced. If consistent long-running computations are
-required, consider using **`irc::extern`**.
-
-`listener`-type scripts are spawned with the variable `chan` set to the
-channel they recieve dispatches over. This will be a **`dict`** with
-contents as described in
+Listener-type handlers are scripts, executed in either a
+sub-interpreter or a seperate thread. Interpreter listeners should
+yield themselves with **`after`** during long operations, and never
+block for extended periods. If that is infeasible, threaded listeners
+are recommended.
+
+`listener`-type scripts are spawned with the variable `dispatch` set to
+the channel they are to recieve dispatches over. Each line will be a
+**`dict`** with contents as described in
[Event Dispatch Contents](#event-dispatch-contents).
-They are given access to the
-[Dispatch-aliased IRC commands](dispatch-aliased-irc-commands).
+Interpreters are given access to the
+[Dispatch-aliased IRC commands](dispatch-aliased-irc-commands), while
+threads are given the variable `parent`, the ID of the main thread.
When a listener is removed, it will recieve a message of just `end`. It
-should perform necessary cleanup quickly, and return, as the
-application is likely exiting, and it may not be re-executed if it
-yields.
+should perform necessary cleanup quickly, as the application is likely
+exiting. Threads may simply **`thread::release`** themselves, while
+interps may call the provided **`selfdestruct`**.
-### `irc::listener add `*`chan patlist script`*
+### `irc::listener add `*`chan ?-thread? patlist script`*
Registers `script` as a listener-type handler on `chan`, matching
`patlist` as [described below](#message-pattern-lists). Returns an id
that can be passed to **`irc::listener remove`** or **`irc::patlist`**.
+If `-thread` is passed, it will be created as a threaded listener,
+otherwise it will be created in a sub-interpreter.
+
### `irc::listener remove `*`chan id`*
Unregisters the listener identified by `id` from `chan`.
+Ignores requests for nonexistent handlers or handlers of the wrong type.
+
## `irc::handler `*`subcommand chan ?arg ...?`*
Configure handler-type event handlers.
Handler-type event handlers execute a script everytime a message is
-matched. For application responsiveness and stability reasons, it is
-expected that handler scripts will not take longer than 100ms to
-execute, though this is not enforced.
-
-Handlers can be created with or without a stored interpreter. If
-created without, they will be spawned with a new interpreter for each
-message, and clean scope.
+matched. These scripts can be executed in either the global scope, a
+sub-interpreter, or a seperate thread.
`handler`-type scripts are spawned with the variable `dispatch` set as
described in
[Event Dispatch Contents](#event-dispatch-contents).
-They are given access to the
-[Dispatch-aliased `irc` commands](dispatch-aliased-codeirccode-commands).
+Interpreters are given access to the
+[Dispatch-aliased `irc` commands](dispatch-aliased-codeirccode-commands),
+while threads are given the variable `parent`, the ID of the main
+thread.
+
+When a handler is removed, if it has an interpreter or thread, it
+will be deleted. Applications with persistent state should take care to
+store it to disk after each command, or use one of the other dispatch
+types.
-When a handler is removed, if it has a stored interpreter, it will be
-deleted. Applications with persistent state should take care to store
-it to disk after each command, or use one of the other dispatch types.
+It is essentially assumed that an individual `handler` will have
+exclusive ownership of its sub-interpreter or thread.
-### `irc::handler add `*`chan patlist script ?interp?`*
+### `irc::handler add `*`chan ?-thread? patlist script ?interp-or-thread?`*
Registers `script` as a handler-type handler on `chan`, matching
`patlist` as [described below](#message-pattern-lists). Returns an id
that can be passed to **`irc::extern remove`** or **`irc::patlist`**.
-If `interp` is supplied, `script` will be added as a stored-interpreter
-handler, with `interp` as the stored-interpreter. The same alias setup
-performed on internally created interpreters will be performed, once, on
-the supplied interpreter, and `dispatch` will be set just before
-executing `script`.
+If neither `-thread` nor `interp-or-thread` are set, `script` will be
+executed in the global scope. If `interp-or-thread` is set, it is the
+ID of the interpreter to execute the script in. If `-thread` is set,
+`script` is executed in a persistent seperate thread. If `-thread` and
+`interp-or-thread` are set, `interp-or-thread` is the ID of the thread
+to use.
-### `irc::extern remove `*`chan id`*
+### `irc::handler remove `*`chan id`*
-Unregisters the extern handler identified by `id` from `chan`.
+Unregisters the handler-type event handler identified by `id` from `chan`.
+
+Ignores requests for nonexistent handlers or handlers of the wrong type.
## `irc::extern `*`subcommand chan ?arg ...?`*
@@ 151,7 159,7 @@ be written to it. The dispatch pipe is never closed by `irc.tcl`. The
reply pipe will be closed immediately. Ensure code that uses multiple
handlers accounts for this.
-### `irc::handler add `*`chan patlist ochan ichan`*
+### `irc::extern add `*`chan patlist ochan ichan`*
Registers `ochan` and `ichan` as the dispatch and reply pipes of a
extern-type handler on `chan`, matching `patlist` as
@@ 162,6 170,8 @@ be passed to **`irc::extern remove`** or **`irc::patlist`**.
Unregisters the extern handler identified by `id` from `chan`.
+Ignores requests for nonexistent handlers or handlers of the wrong type.
+
## `irc::patlist `*`chan id ?patlist?`*