Limnoria abstracts its internal architecture away from plugins through its plugin API, which is enough most of the time. However, you may need want to understand its internal architecture, either to debug complex problems, provide advanced features that hook into the internals, contribute to the core, or simply out of curiosity.
This guide will try to walk you through this, assuming you are already familiar with using the bot and writing plugins (if not, see the Capabilities documentation, the Writing Your First Limnoria Plugin, and Special methods and catching events,
You should also be somewhat familiar with the IRC protocol.
This document is a work in progress and is still incomplete. As usual, feel free to ask any questions in #limnoria @ Libera.
Main loop and drivers¶
The main event loop is a very classic synchronous loop.
It is defined in
scripts/supybot, and essentially just this:
while world.ircs: try: drivers.run() except KeyboardInterrupt: # Handle Ctrl-C (trigger shutdown) except: # Handle other unhandled errors
drivers.run() does this:
for (name, driver) in _drivers.items(): if name not in _deadDrivers: driver.run() for name in _deadDrivers: # Remove the driver while _newDrivers: (name, driver) = _newDrivers.pop() # add the new driver
Drivers are the sources of events in the main thread. In a normal Limnoria
setup, there are two types of drivers: the Socket driver (which connects
synchronously to IRC) and the schedule driver
(which runs functions periodically, like cron).
Historically, there was an alternative driver to connect to IRC,
based on Twisted. It was deprecated, then removed in 2019, because
socket module became as powerful as Twisted as it gained
select() and TLS.
Network drivers have a reference to a
irclib.Irc object, and
do three things in their
check the connection is still alive (and schedule a reconnect if not)
get new messages from their
supybot.irclib.Irc.takeMsg()) and send them to the network
get new messages from the network and pass them to their
The actual implementation of the current
Socket driver is actually
a little more complex than this, as all
Socket driver instances cooperate
select() together, but this is the rough idea.
src/drivers/Socket.py for details.
As we saw above, network drivers pass their messages to a class defined in
irclib, which is where most of the IRC protocol implementation is.
Unlike most event-driven software (especially IRC implementation), Limnoria
does not have hooks that are registered to call a function when a specific
event/IRC command is received.
Instead, event listeners receive all events, and inherit on
supybot.irclib.IrcCommandDispatcher, which calls a specific method
based on the IRC command name. For example, it calls the
when receiving a
This dispatching is used both in the main IRC handling
supybot.irclib.Irc) and plugins (via
supybot.callbacks.PluginMixin, which inherits
We saw above that the
supybot.irclib.Irc object receives messages
directly from the driver. It’s also in charge of keeping track of other
callbacks (ie. plugins) via
supybot.irclib.Irc.addCallback() and passing
every message to their
__call__ method (which then does the dispatching
on its own again, as it inherits
As there are few callbacks (under a hundred plugins), this simple architecture is efficient enough.
Additionally, when receiving a message and before sending one, it iterates
through the list of plugins and calls their
methods (respectively), if any.
If you look at the code of
supybot.irclib.IrcState, you see they are mostly made of
methods, which exhaustively implement every known IRC command, update some
state, and optionally react to it by queuing messages.
Next is the callbacks system, mostly implemented in
This is where all the magic happens to make plugins so easy to write;
it’s also the most complex part of Limnoria and the hardest to understand,
because everything is tightly interleaved.