What is the difference between rocket::ignite() and rocket::build()?

Shinomoto Asakura 0
Viewed 42

I'm learning rocket framework and I came a cross with method after you launch the application.

#[launch]
fn rocket() -> _ {
    rocket::build().mount("/", routes![index])
}

or without attribute "launch"

fn main() {
    rocket::ignite()
        .mount("/", routes![index])
        .launch();
}
rust-rocket rust
1 Answers

From the documentation, rocket::ignite() from version 0.4 is pretty much identical to rocket::build() from version 0.5. They both load the configuration (see 0.4 guide and 0.5 guide) and create the Rocket isntance in a state for you to .mount() routes, .manage() state, .attach() fairings, and other such customizations.

The big difference with initialization in version 0.5 is the Rocket type now uses a typestate pattern to encode the different "phases" that an application instance can be in:

  • Rocket<Build>: This is the only phase in which an instance can be modified. To finalize changes, an instance is ignited via Rocket::ignite(), progressing it into the ignite phase, or directly launched into orbit with Rocket::launch() which progress the instance through ignite into orbit.
  • Rocket<Ignite>: An instance in the Ignite phase is in its final configuration, available via Rocket::config(). Barring user-supplied interior mutation, application state is guaranteed to remain unchanged beyond this point. An instance in the ignite phase can be launched into orbit to serve requests via Rocket::launch().
  • Rocket<Orbit>: An instance in the Orbit phase represents a running application, actively serving requests.

The wording did change since "ignition" used to happen before configuration but now it happens after (which makes more sense to me). The general flow of creating a Rocket server is no different, just the typestate pattern helps enforce consistency and expectations. You generally don't see the other states like Rocket<Orbit>, except if you use a Fairing.

The #[launch] attribute is new in 0.5 and does a number of things. Crucially it starts an async runtime since Rocket is 100% asynchronous as of 0.5. It also creates your main() function, if you didn't want that then you can use the #[rocket::main] attribute on your own main() instead. Then it then calls .launch() on your Rocket<Build> instance and .awaits the result; in other words, it starts the server.

kmdreko0
Related