expose main-loop file descriptor hooks

(cherry picked from commit 92d39cd077)

docs/plugin-api-additions/events.md

@@ -1,26 +0,0 @@
-# Semantic IRC hooks
-
-`on_join`, `on_part`, `on_quit`, `on_nick`, `on_kick`, `on_message`, and
-`on_notice` accept `(callback, userdata=None, priority=PRI_NORM)`. The general
-form is `hook_event(command, callback, userdata=None, priority=PRI_NORM)`.
-Callbacks receive `(event, userdata)`, where the immutable IRCEvent has
-command, prefix, nick, user, host, params, context, connection_id and time.
-`params` preserves the trailing parameter, including spaces; JOIN parameters
-also retain extended-join account/realname data when supplied by the server.
-
-These wrappers use existing server hooks, before core command processing;
-return the ordinary EAT_* constants. EAT_ZOITECHAT suppresses the entire IRC
-command (including client state updates), not just its text. Use EAT_NONE for
-observation. Other plugins' priority and eating rules remain unchanged.
-The context is the core-selected context, which can be the server tab when a
-query/channel does not yet exist. QUIT is one event per incoming command,
-not one callback per affected channel. `event.time` is the existing server-time
-attribute (zero when unavailable); other message tags are not exposed here.
-
-```python
-def joined(event, userdata):
-    event.context.prnt('{} joined {}'.format(event.nick, event.params[0]))
-    return zoitechat.EAT_NONE
-
-zoitechat.on_join(joined)
-```

docs/plugin-api-additions/fd.md

@@ -0,0 +1,19 @@
+# Python descriptor hooks
+
+`hook_fd(fd, callback, userdata=None, flags=FD_READ)` returns an ordinary hook
+handle accepted by `unhook()`. Callback arguments are `(fd, ready_flags, userdata)`;
+return True to retain the watch and False/None to remove it. Exceptions print a
+traceback and remove the watch. Unloading the script removes its watches.
+The callback runs in the context captured during registration, and that context
+is restored afterwards. A closed context removes the watch.
+
+Use nonblocking IO and bounded reads/writes. The descriptor belongs to the script;
+unhook before closing it. On Windows socket descriptors use the default flags;
+CRT descriptors need FD_NOTSOCKET. The existing C API uses int descriptors: values
+outside its range are rejected rather than truncated. This does not add threads.
+
+Example:
+```python
+watch = zoitechat.hook_fd(sock.fileno(), on_readable, flags=zoitechat.FD_READ)
+# def on_readable(fd, flags, userdata): ...; return True
+```

plugins/python/_zoitechat_events.py

@@ -1,77 +0,0 @@
-"""Structured, opt-in hooks before the IRC command's core processing."""
-from collections import namedtuple
-import _zoitechat as api
-
-__all__ = ['IRCEvent', 'hook_event', 'on_join', 'on_part', 'on_quit',
-           'on_nick', 'on_kick', 'on_message', 'on_notice']
-IRCEvent = namedtuple('IRCEvent', 'command prefix nick user host params context connection_id time')
-_SUPPORTED = frozenset(('JOIN', 'PART', 'QUIT', 'NICK', 'KICK', 'PRIVMSG', 'NOTICE'))
-
-
-def _parse(line):
-    prefix = ''
-    if line.startswith(':'):
-        prefix, separator, line = line[1:].partition(' ')
-        if not separator:
-            return None
-    command, separator, rest = line.partition(' ')
-    params = []
-    while rest:
-        rest = rest.lstrip(' ')
-        if rest.startswith(':'):
-            params.append(rest[1:])
-            break
-        param, separator, rest = rest.partition(' ')
-        if param:
-            params.append(param)
-    nick, marker, userhost = prefix.partition('!')
-    user, marker, host = userhost.partition('@')
-    return command.upper(), prefix, nick, user, host, tuple(params)
-
-
-def hook_event(command, callback, userdata=None, priority=api.PRI_NORM):
-    """callback(event, userdata) returns existing EAT_* constants."""
-    command = command.upper()
-    if command not in _SUPPORTED:
-        raise ValueError('unsupported semantic event: ' + command)
-    if not callable(callback):
-        raise TypeError('callback must be callable')
-
-    def dispatch(word, word_eol, data, attrs):
-        if not word_eol:
-            return api.EAT_NONE
-        parsed = _parse(word_eol[0])
-        if parsed is None or parsed[0] != command:
-            return api.EAT_NONE
-        event = IRCEvent(*(parsed + (api.get_context(), api.get_prefs('id'), attrs.time)))
-        return callback(event, data)
-
-    return api.hook_server_attrs(command, dispatch, userdata, priority)
-
-
-def on_join(callback, userdata=None, priority=api.PRI_NORM):
-    return hook_event('JOIN', callback, userdata, priority)
-
-
-def on_part(callback, userdata=None, priority=api.PRI_NORM):
-    return hook_event('PART', callback, userdata, priority)
-
-
-def on_quit(callback, userdata=None, priority=api.PRI_NORM):
-    return hook_event('QUIT', callback, userdata, priority)
-
-
-def on_nick(callback, userdata=None, priority=api.PRI_NORM):
-    return hook_event('NICK', callback, userdata, priority)
-
-
-def on_kick(callback, userdata=None, priority=api.PRI_NORM):
-    return hook_event('KICK', callback, userdata, priority)
-
-
-def on_message(callback, userdata=None, priority=api.PRI_NORM):
-    return hook_event('PRIVMSG', callback, userdata, priority)
-
-
-def on_notice(callback, userdata=None, priority=api.PRI_NORM):
-    return hook_event('NOTICE', callback, userdata, priority)

plugins/python/_zoitechat_fd.py

@@ -0,0 +1,39 @@
+"""File descriptor readiness hooks; callbacks execute on the main thread."""
+import operator
+import _zoitechat as api
+from _zoitechat_embedded import ffi, lib
+
+__all__ = ['FD_READ', 'FD_WRITE', 'FD_EXCEPTION', 'FD_NOTSOCKET', 'hook_fd']
+FD_READ, FD_WRITE, FD_EXCEPTION, FD_NOTSOCKET = 1, 2, 4, 8
+
+
+def hook_fd(fd, callback, userdata=None, flags=FD_READ):
+    """callback(fd, ready_flags, userdata): True keeps the watch, False removes it."""
+    fd = operator.index(fd)
+    flags = operator.index(flags)
+    if fd < 0 or fd > 2147483647:
+        raise ValueError('fd must fit the C API nonnegative int descriptor')
+    if flags & ~15 or not flags & 7:
+        raise ValueError('flags must select READ, WRITE or EXCEPTION')
+    if not callable(callback):
+        raise TypeError('callback must be callable')
+    plugin = api.__get_current_plugin()
+    context = api.get_context()
+
+    def dispatch(descriptor, ready, data):
+        previous = api.get_context()
+        if not context.set():
+            return False
+        try:
+            return callback(descriptor, ready, data)
+        finally:
+            previous.set()
+
+    hook = plugin.add_hook(dispatch, userdata)
+    handle = lib.zoitechat_hook_fd(lib.ph, fd, flags, lib._on_fd_hook, hook.handle)
+    if handle == ffi.NULL:
+        hook.is_unload = True
+        plugin.remove_hook(id(hook))
+        raise RuntimeError('unable to watch descriptor')
+    hook.zoitechat_hook = handle
+    return id(hook)

plugins/python/generate_plugin.py

@@ -38,6 +38,7 @@ extern "Python" int _on_print_attrs_hook(char **, zoitechat_event_attrs *, void
 extern "Python" int _on_server_hook(char **, char **, void *);
 extern "Python" int _on_server_attrs_hook(char **, char **, zoitechat_event_attrs *, void *);
 extern "Python" int _on_timer_hook(void *);
+extern "Python" int _on_fd_hook(int, int, void *);
 
 extern "Python" int _on_plugin_init(char **, char **, char **, char *, char *);
 extern "Python" int _on_plugin_deinit(void);

plugins/python/python.py

@@ -304,6 +304,28 @@ def _on_timer_hook(userdata):
     return 0
 
 
+@ffi.def_extern()
+def _on_fd_hook(fd, flags, userdata):
+    hook = ffi.from_handle(userdata)
+    keep = False
+    try:
+        keep = bool(hook.callback(fd, flags, hook.userdata))
+    except Exception:
+        traceback.print_exc()
+    if not keep:
+        # The C watch removes itself on return; do not unhook it a second time.
+        try:
+            hook.is_unload = True
+            # from_handle() yields a weak proxy: id(proxy) is not id(Hook).
+            for existing in hook.plugin.hooks:
+                if existing == hook:
+                    hook.plugin.remove_hook(id(existing))
+                    break
+        except ReferenceError:
+            pass  # the callback already unhooked itself
+    return int(keep)
+
+
 @ffi.def_extern()
 def _on_say_command(word, word_eol, userdata):
     """Handle input in the special >>python<< tab.