Need help with state management (save+load) in Relm4 apps

[chriskilding]

I am currently trying to work out how Relm4 apps should persist and load state (e.g. to a file or to an HTTP API).

I see the following things in the Relm4 API, each of which looks like they might provide part of a solution, but none of them is a whole solution:

• SharedState / Reducer
• MessageBroker
• Commands / Workers / headless components

I am aware of the Subscriptions and Commands concepts in Elm, which Relm4 is (at least partially) based on, but I don't see how exactly they would translate into Relm4 - or if either of them has been implemented in Relm4 yet.

The GAME_STATE in examples/libadwaita/tab_game.rs helps a bit, but unfortunately not much, because the game state in that example is a single static global variable. This is not realistic because in many apps, state must be scoped and stored per-document or per-user, but the example doesn't show how you might pass a SharedState around within Components or attach it to them.

I therefore need use some help in understanding how to put the pieces together to form, for example, a document-based app.

Example

This is a simplified tic-tac-toe example. It's incomplete at the moment; I'll need your help to complete it with the state management.

Some of the questions that immediately arise are:

• Can Reducer be used for this purpose, or do you effectively need to use SharedState for the Game (because the app will bind the game model values in the UI)?
• How would you pass the Game around to the view Components? (Simply as an instance variable passed in the fn init(...) method?)

Additionally, a more sophisticated version of this app could have multiple tabs/windows, where each Game is shown in its own window. How would the Game Reducer/SharedState be created for each window in this case?

(If we get this up to a good standard, we can then add a new page in the Relm book covering state management, with this as an example.)

// Game of tic-tac-toe

use relm4::prelude::*;
use gtk::prelude::*;
use relm4::Reducer;
use serde::{Deserialize, Serialize};

// The view

struct GameView {
    // document state which is external to the Component, intended to be saved/loaded
    game: Reducer<Game>,

    // local state within the Component
    foo: String,
}

#[derive(Debug)]
enum GameViewInput {
    Play(usize, usize),
}

#[relm4::component(pub)]
impl SimpleComponent for GameView {
    type Input = GameViewInput;
    type Output = ();
    type Init = Reducer<Game>;

    view! {
        #[root]
        gtk::Box {
            set_orientation: gtk::Orientation::Vertical,

            gtk::Label {
                set_text: &model.foo,
            },

            gtk::Grid {
                // TODO attach each piece in the board as a gtk::Button
                // when clicked it should raise a GameViewInput::Play event with its x/y coordinates
            }
        }
    }

    fn init(init: Self::Init, root: &Self::Root, sender: ComponentSender<Self>) -> ComponentParts<Self> {
        let model = Self {
            game: init,
            foo: String::from("Hello"),
        };

        let widgets = view_output!();

        ComponentParts { model, widgets }
    }

    fn update(&mut self, message: Self::Input, sender: ComponentSender<Self>) {
        match message {
            GameViewInput::Play(x, y) => {
                self.game.emit(GameInput::Play(x, y));
            }
        }
    }
}




// The 'document'
#[derive(Debug, Deserialize, Serialize)]
struct Game {
    board: Board,
    current_player: Player,
}

type Board = Vec<Vec<Piece>>;

#[derive(Debug, Deserialize, Serialize)]
enum Player {
    X,
    O,
}

impl Player {
    fn other(&self) -> Player {
        match self {
            Player::X => Player::O,
            Player::O => Player::X,
        }
    }
}

#[derive(Debug, Deserialize, Serialize)]
enum Piece {
    X,
    O,
    Empty,
}

enum GameInput {
    Play(usize, usize),
    Clear,
}

impl relm4::Reducible for Game {
    type Input = GameInput;

    fn init() -> Self {
        let board = vec![
            vec![Piece::Empty, Piece::Empty, Piece::Empty],
            vec![Piece::Empty, Piece::Empty, Piece::Empty],
            vec![Piece::Empty, Piece::Empty, Piece::Empty],
        ];

        let current_player = Player::X;

        Self {
            board,
            current_player
        }
    }

    fn reduce(&mut self, input: Self::Input) -> bool {
        match input {
            GameInput::Play(x, y) => {
                let piece = match self.current_player {
                    Player::X => Piece::X,
                    Player::O => Piece::O,
                };

                // bounds checking not included
                self.board[x][y] = piece;

                self.current_player = self.current_player.other();
            }
            GameInput::Clear => {
                // TODO reset all the board slots to Piece::Empty
            }
        }

        true
    }
}

// The app wrapper
// Each Game instance is in its own window/tab.

struct App {
    game: Reducer<Game>,
    game_view: Controller<GameView>,
}

#[derive(Debug)]
enum AppInput {
    NewGame,
    SaveGame,
    LoadGame,
}

#[relm4::component(pub)]
impl SimpleComponent for App {
    type Input = AppInput;
    type Output = ();
    type Init = ();

    view! {
        #[root]
        main_window = gtk::ApplicationWindow {
            set_default_width: 640,
            set_default_height: 480,

            gtk::Box {
                set_orientation: gtk::Orientation::Vertical,

                gtk::HeaderBar {
                    #[wrap(Some)]
                    set_title_widget = &gtk::Label {
                        set_text: "Tic Tac Toe",
                    },

                    pack_start = &gtk::Button {
                        set_label: "New Game",
                        connect_clicked => AppInput::NewGame,
                    },

                    pack_end = &gtk::Button {
                        set_label: "Save Game",
                        connect_clicked => AppInput::SaveGame,
                    },

                    pack_end = &gtk::Button {
                        set_label: "Load Game",
                        connect_clicked => AppInput::LoadGame,
                    }
                },

                model.game_view.widget(),
            }
        }
    }

    fn init(init: Self::Init, root: &Self::Root, sender: ComponentSender<Self>) -> ComponentParts<Self> {
        // this is the game document that will be displayed in the window
        let game: Reducer<Game> = Reducer::new();

        let game_view = GameView::builder()
            .launch(game)
            .detach();

        let model = Self {
            game, // FIXME not quite right
            game_view
        };

        let widgets = view_output!();

        ComponentParts { model, widgets }
    }

    fn update(&mut self, message: Self::Input, sender: ComponentSender<Self>) {
        match message {
            AppInput::NewGame => {
                self.game.emit(GameInput::Clear)
            }
            AppInput::SaveGame => {
                // TODO present SaveDialog, get path, call save_game(...)
            }
            AppInput::LoadGame => {
                // TODO present OpenDialog, get path, call load_game(...), update game reducer
            }
        }
    }
}

fn main() {
    let app = RelmApp::new("org.relm4.examples.TicTacToe");

    app.run::<App>(());
}


// De/Serializer logic
// (error handling not included)
// TODO wrap these in a headless Component or Worker so that the I/O is done asynchronously
fn save_game(game: Game, path: std::path::PathBuf) {
    let json = serde_json::to_string(&game).unwrap();
    std::fs::write(path, json).unwrap()
}

fn load_game(path: std::path::PathBuf) -> Game {
    let json = std::fs::read_to_string(path).unwrap();
    serde_json::from_str(&*json).unwrap()
}

[AaronErhardt]

Can Reducer be used for this purpose, or do you effectively need to use SharedState for the Game (because the app will bind the game model values in the UI)?

Reducer uses a subscription based approach, so you can't access the data directly. SharedState was designed for sharing (global) information across components.

How would you pass the Game around to the view Components? (Simply as an instance variable passed in the fn init(...) method?)

I'm not sure if Relm4 has a proper solution for this problem yet. In general, sharing state in Rust is sometimes tricky. The most standard approach I can think of is Rc<RefCell<T>>, but I'm not sure if that works for you.

I think this is a good example find missing features in Relm4, I hope we can come up with a satisfying solution. Maybe we should first take a step back and think about how you would ideally want to deal with game state and then come up with a solution to map this to Rust code.

[chriskilding]

Thanks for your comments - I think that indeed this is one of those cases where I have stumbled into a missing feature, but if we can come up with a good solution for it then it will enable a lot of new state-based apps to be created with Relm4.

---

I circled round for another go and switched from Reducer to SharedState - which has turned out to be the more promising approach for modelling the document that contains the persistent state. (Mainly because it can actually be bound to GTK elements, whereas Reducer cannot.)

The next problem I ran into, however, was where to store the SharedState<Game> instance given that multiple views need to access it - the GameView (which contains the tic-tac-toe board) and the App (which contains the toolbar with the New Game / Save Game / Load Game buttons).

I tried initialising it within the App#init method, using the following approaches:

• Both App and GameView are passed the full SharedState<Game>. This doesn't work because only one thing can own it.
• Both App and its child GameView get references to the &SharedState<Game>, neither owns it. This doesn't work because the Game object will go out of scope at the end of init.
• Store the SharedState<Game> instance on the App. So App gets full ownership, while all other views get references. This doesn't work because although the enclosing App object will keep the SharedState<Game> alive, you run into Rust lifetime specifier errors with the reference. (I did not find a combination of lifetime specifiers that would make the compiler happy.)

The takeaway so far is that with the existing features of Relm4, SharedState is definitely the way to go, but there's a lot of unanswered questions about how to make it work.

V2 code below:

///
/// Game of tic-tac-toe
///

use std::fmt::{Debug, Display, Formatter};
use relm4::prelude::*;
use gtk::prelude::*;
use relm4::{SharedState};
use serde::{Deserialize, Serialize};

const DEFAULT_SPACING: i32 = 5;

///
/// The view
///

struct GameView {
    // document state which is external to the Component, intended to be saved/loaded
    game: SharedState<Game>,

    // local state within the Component
    foo: String,
}

#[derive(Debug)]
enum GameViewInput {
    Play(usize, usize),
}

#[relm4::component(pub)]
impl SimpleComponent for GameView {
    type Input = GameViewInput;
    type Output = ();
    type Init = SharedState<Game>;

    view! {
        gtk::Box {
            set_orientation: gtk::Orientation::Vertical,
            set_spacing: DEFAULT_SPACING,

            gtk::Box {
                set_spacing: DEFAULT_SPACING,

                gtk::Label {
                    set_text: "Foo:"
                },

                gtk::Label {
                    set_text: &model.foo,
                },
            },

            gtk::Box {
                set_spacing: DEFAULT_SPACING,

                gtk::Label {
                    set_text: "Current Player:"
                },

                gtk::Label {
                    #[watch]
                    set_text: &model.game.read().current_player.to_string(),
                }
            },

            gtk::Grid {
                set_row_spacing: 5,
                set_column_spacing: 5,

                // lots of duplication in here to clean up
                attach[0, 0, 1, 1] = &gtk::Button {
                    #[watch]
                    set_label: &model.game.read().board[0][0].to_string(),

                    #[watch]
                    set_sensitive: model.game.read().board[0][0] == Piece::Empty,

                    connect_clicked => GameViewInput::Play(0, 0),
                },

                attach[1, 0, 1, 1] = &gtk::Button {
                    #[watch]
                    set_label: &model.game.read().board[1][0].to_string(),

                    #[watch]
                    set_sensitive: model.game.read().board[1][0] == Piece::Empty,

                    connect_clicked => GameViewInput::Play(1, 0),
                },

                attach[2, 0, 1, 1] = &gtk::Button {
                    #[watch]
                    set_label: &model.game.read().board[2][0].to_string(),

                    #[watch]
                    set_sensitive: model.game.read().board[2][0] == Piece::Empty,

                    connect_clicked => GameViewInput::Play(2, 0),
                },

                attach[0, 1, 1, 1] = &gtk::Button {
                    #[watch]
                    set_label: &model.game.read().board[0][1].to_string(),

                    #[watch]
                    set_sensitive: model.game.read().board[0][1] == Piece::Empty,

                    connect_clicked => GameViewInput::Play(0, 1),
                },

                attach[1, 1, 1, 1] = &gtk::Button {
                    #[watch]
                    set_label: &model.game.read().board[1][1].to_string(),

                    #[watch]
                    set_sensitive: model.game.read().board[1][1] == Piece::Empty,

                    connect_clicked => GameViewInput::Play(1, 1),
                },

                attach[2, 1, 1, 1] = &gtk::Button {
                    #[watch]
                    set_label: &model.game.read().board[2][1].to_string(),

                    #[watch]
                    set_sensitive: model.game.read().board[2][1] == Piece::Empty,

                    connect_clicked => GameViewInput::Play(2, 1),
                },

                attach[0, 2, 1, 1] = &gtk::Button {
                    #[watch]
                    set_label: &model.game.read().board[0][2].to_string(),

                    #[watch]
                    set_sensitive: model.game.read().board[0][2] == Piece::Empty,

                    connect_clicked => GameViewInput::Play(0, 2),
                },

                attach[1, 2, 1, 1] = &gtk::Button {
                    #[watch]
                    set_label: &model.game.read().board[1][2].to_string(),

                    #[watch]
                    set_sensitive: model.game.read().board[1][2] == Piece::Empty,

                    connect_clicked => GameViewInput::Play(1, 2),
                },

                attach[2, 2, 1, 1] = &gtk::Button {
                    #[watch]
                    set_label: &model.game.read().board[2][2].to_string(),

                    #[watch]
                    set_sensitive: model.game.read().board[2][2] == Piece::Empty,

                    connect_clicked => GameViewInput::Play(2, 2),
                },
            }
        }
    }

    fn init(init: Self::Init, root: &Self::Root, sender: ComponentSender<Self>) -> ComponentParts<Self> {
        let model = Self {
            game: init,
            foo: String::from("Hello"),
        };

        let widgets = view_output!();

        ComponentParts { model, widgets }
    }

    fn update(&mut self, message: Self::Input, sender: ComponentSender<Self>) {
        match message {
            GameViewInput::Play(x, y) => {
                println!("played at ({}, {})", x, y);

                // bounds checking not included
                let mut g = self.game.write();
                g.board[x][y] = Piece::from(g.current_player);
                g.current_player.toggle();
            }
        }
    }
}

impl From<Player> for Piece {
    fn from(value: Player) -> Self {
        match value {
            Player::X => Piece::X,
            Player::O => Piece::O,
        }
    }
}

///
/// The 'document'
///

#[derive(Debug, Default, Deserialize, Serialize)]
struct Game {
    board: Board,
    current_player: Player,
}

type Board = Vec<Vec<Piece>>;

#[derive(Debug, Copy, Clone, Deserialize, Serialize)]
enum Player {
    X,
    O,
}

impl Display for Player {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        Debug::fmt(self, f)
    }
}

impl Default for Player {
    fn default() -> Self {
        Player::X
    }
}

impl Player {
    fn toggle(&mut self) {
        match self {
            Player::X => {
                *self = Player::O;
            },
            Player::O => {
                *self = Player::X;
            },
        }
    }
}

#[derive(Debug, PartialEq, Copy, Clone, Deserialize, Serialize)]
enum Piece {
    X,
    O,
    Empty,
}

impl Display for Piece {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        let str = match self {
            Piece::X => "X",
            Piece::O => "O",
            Piece::Empty => "",
        };

        write!(f, "{}", str)
    }
}

/// Create a default game on a 3x3 board and Player 'X' starting
fn standard_game() -> SharedState<Game> {
    let game: SharedState<Game> = SharedState::new();

    let board = vec![
        vec![Piece::Empty, Piece::Empty, Piece::Empty],
        vec![Piece::Empty, Piece::Empty, Piece::Empty],
        vec![Piece::Empty, Piece::Empty, Piece::Empty],
    ];
    let current_player = Player::X;

    game.write().board = board;
    game.write().current_player = current_player;

    game
}

///
/// The app wrapper
///

struct App {
    //game: Reducer<Game>,
    game_view: Controller<GameView>,
}

#[derive(Debug)]
enum AppInput {
    NewGame,
    SaveGame,
    LoadGame,
}

#[relm4::component(pub)]
impl SimpleComponent for App {
    type Input = AppInput;
    type Output = ();
    type Init = ();

    view! {
        gtk::ApplicationWindow {
            set_default_width: 640,
            set_default_height: 480,

            gtk::Box {
                set_orientation: gtk::Orientation::Vertical,

                gtk::HeaderBar {
                    set_show_title_buttons: false,

                    pack_start = &gtk::Button {
                        set_label: "New Game",
                        connect_clicked => AppInput::NewGame,
                    },

                    pack_end = &gtk::Button {
                        set_label: "Save Game",
                        connect_clicked => AppInput::SaveGame,
                    },

                    pack_end = &gtk::Button {
                        set_label: "Load Game",
                        connect_clicked => AppInput::LoadGame,
                    }
                },

                model.game_view.widget(),
            }
        }
    }

    fn init(init: Self::Init, root: &Self::Root, sender: ComponentSender<Self>) -> ComponentParts<Self> {
        // this is the game document that will be displayed in the window
        let game = standard_game();

        let game_view = GameView::builder()
            .launch(game)
            .detach();

        let model = Self {
            //game, // TODO store main reference in the top-level App instance
            game_view
        };

        let widgets = view_output!();

        ComponentParts { model, widgets }
    }

    fn update(&mut self, message: Self::Input, sender: ComponentSender<Self>) {
        match message {
            AppInput::NewGame => {
                //TODO self.game.emit(GameInput::Clear)
            }
            AppInput::SaveGame => {
                // TODO present SaveDialog, get path, call save_game(...)
            }
            AppInput::LoadGame => {
                // TODO present OpenDialog, get path, call load_game(...), update game state
            }
        }
    }
}

fn main() {
    let app = RelmApp::new("org.relm4.examples.TicTacToe");

    app.run::<App>(());
}

///
/// (De)Serializer logic
/// TODO: wrap in async Component / Worker
///

fn save_game(game: Game, path: std::path::PathBuf) {
    let json = serde_json::to_string(&game).unwrap();
    std::fs::write(path, json).unwrap()
}

fn load_game(path: std::path::PathBuf) -> Game {
    let json = std::fs::read_to_string(path).unwrap();
    serde_json::from_str(&*json).unwrap()
}

[chriskilding]

Regarding the wider question of how should state management work in Relm4, this is a tricky one. There are several ideas out there about how to do this in other comparable UI frameworks, with varying usability:

• React / Redux has (FP-pure) Reducers and Stores
• Elm has Commands and Subscriptions
• SwiftUI differentiates between Binding and State variables (where State is for temporary state that lives within a SwiftUI View, i.e. the foo variable in the example above, while Binding is for injecting external state into the View which could have come from an external system, i.e. the game variable in the example above)

(Side note: the SharedState in Relm reminds me a bit of SwiftUI Bindings. That doesn't necessarily mean that Relm should continue down that route; it's just a similarity.)

[chriskilding]

I found that it's sufficient to simply wrap the SharedState<...> in an Rc; because SharedState already takes care of the safe state updating aspect, the RefCell part appears to be necessary.

So for example, GameView becomes

struct GameView {
    game: Rc<SharedState<Game>>,

    // ...
}

And App becomes

struct App {
    game: Rc<SharedState<Game>>,
    game_view: Controller<GameView>,
}

And the App#init becomes

fn init(init: Self::Init, root: &Self::Root, sender: ComponentSender<Self>) -> ComponentParts<Self> {
        let game = Rc::new(standard_game());

        let game_view = GameView::builder()
            .launch(Rc::clone(&game))
            .detach();

        let model = Self {
            game: Rc::clone(&game),
            game_view
        };

        let widgets = view_output!();

        ComponentParts { model, widgets }
}

However, while this compiles and runs, I did notice one thing that doesn't work. Updates within the view sync to the model as expected. But if you trigger an update to the model - say the AppInput#NewGame event, which resets the board, the view does not reflect this update immediately. Only when the next interaction happens within the view (e.g. clicking a button), and the Relm update loop runs, does the view get updated with the change.

So I think there's something about using Rc<SharedState<GameView>> wrapper which causes the #[watch] functionality to not work, or ignore updates from the model.