Bash-09
commented
7 months ago The architecture I'm proposing here was inspired by the architecture that Lilith initially suggested, but I've tried to simplify it considerably and work it into something that can be implemented without too much effort and hopefully fairly idiomatically in Rust.
Here is a diagram roughly showing what the control flow for this suggestion might look like when fully implemented to the same feature set that MAC currently has (and slightly more).
Example and API
A demonstration of the interface is shown below, and this prototype also exists in-full on the Bash/EventLoopExperiment branch.
// Define the messages and handlers in a macro like so:
// `define_messages!(MessageEnumName<StateType>: Message1, Message2, Message3, ...);`
// `define_handlers!(HandlerEnumName<StateType, MessageEnumName>: Handler1, Handler2, ...);`
//
// These will create an enum for each of the variants of messages and handlers that were provided, and implements a handful of boilerplate for you. Ending up with essentially:
// enum MessageEnumName {
// Message1(Message1),
// Message2(Message2),
// Message3(Message3),
// }
//
// impl From<Message1> for MessageEnumName {...}
// impl From<Message2> for MessageEnumName {...}
// ...
//
define_messages!(Message<State>: Refresh, NewPlayer, ProfileLookup);
define_handlers!(Handler<State, Message>: GetNewPlayers, LookupProfiles);
pub struct State {}
// Handlers ***************
// Handlers are defined as structs which implement the HandlerStruct<S, M> trait.
// Each cycle of the event loop, `handle_message` is called with each of the messages so it can pattern match and decide to handle it or not.
// The returned Handled<M> type can consist of zero (Handled::none()), one (Handled::single(m)), or multiple
// (Handled::multiple(iter m) command, which can be straight messages or Futures resolving to new messages, which will
// eventually be emitted back into the event loop.
//
// Furthermore, handlers can hold their own state, allowing for batching of results (e.g. steam profile lookups can be accumulated,
// and when the batch fills up enough or time has passed they can all be sent at once. This may require adding a message source
// such as a timer to regularly allow the handler a chance to dispatch) or just to store persistent data like API keys.
pub struct GetNewPlayers;
impl HandlerStruct<State, Message> for GetNewPlayers {
fn handle_message(&mut self, state: &State, message: &Message) -> Handled<Message> {
match message {
Message::Refresh(_) => Handled::single(NewPlayer {}),
_ => Handled::none(),
}
}
}
pub struct LookupProfiles {
pub api_key: Arc<str>,
}
impl HandlerStruct<State, Message> for LookupProfiles {
fn handle_message(&mut self, state: &State, message: &Message) -> Handled<Message> {
match message {
// On new players, send a SteamAPI request for the player's profile
Message::NewPlayer(_) => {
let key = self.api_key.clone();
Handled::future(async move {
let _ = SteamAPI::new(key)
.get()
.ISteamUser()
.GetPlayerSummaries(vec![String::from("")])
.execute()
.await;
Message::ProfileLookup(ProfileLookup {})
})
}
_ => Handled::none(),
}
}
}
// Messages **************
// Messages are defined as structs which implement the StateUpdater<S> trait.
// After entering the event loop queue, the next cycle will pass the message through all of the handlers, and then eventually `update_state` will be called, giving it a chance to make any changes to the state it needs. The default implementation for `update_state` is a noop, so specifying `impl StateUpdater<State> for MessageVariant {}` without actually defining the function inside will just mean the message does not modify the state.
pub struct Refresh;
impl StateUpdater<State> for Refresh {
fn update_state(&self, state: &mut State) {
println!("Refreshing");
}
}
pub struct NewPlayer {}
impl StateUpdater<State> for NewPlayer {}
pub struct ProfileLookup {}
impl StateUpdater<State> for ProfileLookup {
fn update_state(&self, state: &mut State) {
println!("Got profile result!");
}
}
// Main **********************
fn main() {
let (tx, rx) = std::sync::mpsc::channel();
// The event loop itself can be easily constructed with the builder pattern, by creating a new one and appending the different sources and handlers to it.
let mut event_loop: EventLoop<State, Message, Handler> = EventLoop::new()
.add_source(Box::new(rx))
.add_handler(GetNewPlayers {})
.add_handler(LookupProfiles {
api_key: "boop".into(),
});
tokio::runtime::Builder::new_multi_thread()
.enable_all()
.build()
.unwrap()
.block_on(async move {
// Refresh loop
tokio::task::spawn(async move {
let mut refresh_interval = tokio::time::interval(Duration::from_secs(3));
refresh_interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
loop {
refresh_interval.tick().await;
tx.send(Refresh {}).unwrap();
}
});
// Run event loop
let mut state = State {};
loop {
// Call execute_cycle will resolve one cycle of the event loop. In a single cycle:
// - Any futures returned from handlers are polled, adding finished ones to the message queue
// - All queued messages are passed through the handlers and used to update the state
// - All resulting messages from the handlers are added to the message queue for next cycle, and futures are dispatched for a later cycle
event_loop.execute_cycle(&mut state).await;
}
});
}The above example is very simple, but attempts to demonstrate that the behaviour we want to get out of the event loop can be separated with a clean and user-friendly API.
The flow graph for this example is as shown:
Running this example provides the output below:
Running `target/debug/client_backend`
Refreshing
Got profile result!
Refreshing
Got profile result!
Refreshing
Got profile result!
Refreshing
Got profile result!
Refreshing
Got profile result!Further concerns and considerations + RFC
- Reusing existing types outside of the crate
- ~We will be providing a number of message and handler types which MAC will use in the official client, but we also want users to be able to add their own messages and handlers if they want to use the crate in their own project (hence the effort to make the API simple and reuseable). In the current prototype, messages should be perfectly suited to this as they only depend on the state, however handlers also depend on the message enum type, so defining a new set of messages will make the existing handlers incompatible. I have an idea to resolve this, but am yet to see if it will work.~
- I've managed to work around this with the
Is<T>trait, so a handler can be defined with a generic implementingIs<T>for each of the message types it needs to function, as shown below. It's slightly verbose, but I think it's still a decent solution. Handlers defined by the set of message structs they need like this can be used for any message enum defined by the macro that contains all the required types.pub struct GetNewPlayers; impl<M: Is<Refresh> + Is<NewPlayer>> HandlerStruct<State, M> for GetNewPlayers { fn handle_message(&mut self, state: &State, message: &M) -> Handled<M> { let m: Option<&Refresh> = message.try_get(); match m { Some(_) => Handled::single(NewPlayer {}), None => Handled::none(), } } }
- Blocking messages from updating state?
- e.g. When chat messages come in, they are only the player name and text, which in some cases may be all a user wants and they are happy for it to update the state and add it to a chat log. On the other hand, perhaps the user wants to install a handler that attempts to resolve the player's name to the steamid of someone of the server, in which case we would want the resolved chat message to update the state, but not the original one. Should the handler have the ability to block the message from updating as another message will do that in the future? Or perhaps there should be multiple message types for chat so one can update without resolving, one doesn't update while not resolved, and one to update after having been resolved?
- I had another concern I wanted to write out but forgot. If I remember I'll update this and add it in.
If anybody has anything they would like to add to this, please feel free to share your ideas/suggestions/concerns/whatever here or ping me in the MSB discord server. For now I will continue investigating ways to solve any remaining issues with this implementation, and potentially implementing the necessary components to get this closer to replacing the nasty spaghetti we've got currently.
@Bash-09 and myself have been theory crafting and discussing a way to re-engineer the core event loop of the backend into a more distinct and well-structured paradigm that enforces the various principles we want to enforce around server state manipulation and implementation design.
We both have our own ideas and opinions for what a core event loop should do, and this ticket will be the place to discuss and plan.
We both think that the core event loop should be composable and distinctly modifiable by developers importing our crate, and that it should also be built by the rustic builder paradigm and house a self-contained chunk of infrastructure that does a majority of the boilerplate work.