litecord/docs/pubsub.md

Pub/Sub (Publish/Subscribe)

Please look over wikipedia or other sources to understand what it is. This only documents how an events are generated and dispatched to clients.

Event definition

Events are composed of two things:

• Event type
• Event payload

More information on how events are structured are in the Discord Gateway API documentation.

StateManager (litecord.gateway.state_manager)

StateManager stores all available instances of GatewayState that identified. Specific information is over the class' docstring, but we at least define what it does here for the next class:

EventDispatcher (litecord.dispatcher)

EventDispatcher declares the main interface between clients and the side-effects (events) from topics they can subscribe to.

The topic / channel in EventDispatcher can be a User, or a Guild, or a Channel, etc. Users subscribe to the channels they have access to manually, and get unsubscribed when they e.g leave the guild the channel is on, etc.

Channels are identified by their backend and a given key uniquely identifying the channel. The backend can be guild, member, channel, user, friend, and lazy_guild. Backends can store the list of subscribers, but that is not required.

Each backend has specific logic around dispatching a single event towards all the subscribers of the given key. For example, the guild backend only dispatches events to shards that are properly subscribed to the guild, instead of all shards. The user backend just dispatches the event to all available shards in StateManager, etc.

EventDispatcher also implements common logic, such as dispatch_many to dispatch a single event to multpiple keys in a single backend. This is useful e.g a user is updated and you want to dispatch USER_UPDATE events to many guilds without having to write a loop yourself.

Backend superclasses (litecord.pubsub.dispatcher)

The backend superclasses define what methods backends must provide to be fully functional within EventDispatcher. They define e.g what is the type of the keys, and have some specific backend helper methods, such as _dispatch_states to dispatch an event to a list of states without worrying about errors or writing the loop.

The other available superclass is DispatchWithState for backends that require a list of subscribers to not repeat code. The only required method to be implemented is dispatch() and you can see how that works out on the backends that inherit from this class.

Sending an event, practical

Call app.dispatcher.dispatch(backend_string, key, event_type, event_payload).

example:

• dispatch('guild', guild_id, 'GUILD_UPDATE', guild), and other backends. The rules on how each backend dispatches its events can be found on the specific backend class.