mirror of https://gitlab.com/litecord/litecord.git
67 lines
2.7 KiB
Markdown
67 lines
2.7 KiB
Markdown
# 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.
|