Plugincrafting: special top level functions

On certain events, the bot will call specific top-level functions in all plugin modules. They are not called if they are not available, so there's no need to define empty ones.

Preferably do not use your plugin's constructors and destructors. Notably, any action that invokes the garbage collector in the destructor is likely to cause the program to crash.

void initialise(MyPlugin)

This is called after the plugin has been instantiated but before connecting.

Use-cases

When you have some code that you want run as early as possible.

void setup(MyPlugin)

This is called to set up the plugin and acts as a post-connection-established plugin constructor.

Use-cases

Put simply, when you want your plugin to initialise itself. A setup might do things like preallocate buffers in preparation for events to start rolling in.

void teardown(MyPlugin)

This is the opposite of setup and acts as a plugin destructor.

Use-cases

Use it to shut down cleanly at any point. This may be at program benign exit, at program abort exit, upon reconnecting to a server, etc.

void initResources(MyPlugin)

This is called before connection is attempted, but after address resolution. Used to let plugins initialise their resources; files or otherwise. It should create them if they don't exist, but preferably not read them into memory. Do that at setup.

Use-cases

Meant to be used to create files (such as JSON files) if they don't exist, so that they can be assumed to be in place later. The usual approach for JSON files is to read any existing files and write them back out. This validates the JSON.

void postprocess(MyPlugin, ref IRCEvent)

This is called after an event has been parsed but before it is passed to plugins to react upon, to let plugins modify the event before it is passed around.

Use-cases

Used when your plugin is of a kind that wants to modify incoming events for the benefit of other plugins in addition to itself.

void onBusMessage(MyPlugin, string, shared Sendable)

This is called when a boxed bus message is sent between plugins. Use the header string to determine whether or not it was aimed toward your plugin.

Use-cases

Used for inter-plugin communication.

void reload(MyPlugin)

This is called when a call to reload plugins comes along. What this does is implementation-defined.

Use-cases

Generally used to re-read resource files.

bool tick(MyPlugin)

This is called once per main event loop iteration. Its use is situational. Returning true conveys the meaning "something happened, check concurrency messages".

Use-cases

Used in very special cases where a plugin wants to be updated as often as possible (within reason), where an event handler annotated to be called on IRCEvent.Type.ANY is insufficient.

bool selftest(MyPlugin, Selftester)

Called for a plugin to self-test itself.

Use-cases

To perform live-testing of a plugin's commands and behaviour.