From 52479f5c657d790fa99509055ed138b57e556111 Mon Sep 17 00:00:00 2001 From: Aleteoryx Date: Thu, 15 Aug 2024 22:30:20 +0100 Subject: [PATCH] update for commit 614b00a3 --- irc.tcl.md | 86 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 48 insertions(+), 38 deletions(-) diff --git a/irc.tcl.md b/irc.tcl.md index c9bcfdf..a99405b 100644 --- a/irc.tcl.md +++ b/irc.tcl.md @@ -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?`* -- 2.43.4