diff --git a/lib/src/request/state.rs b/lib/src/request/state.rs index d6f2150b..28d373ae 100644 --- a/lib/src/request/state.rs +++ b/lib/src/request/state.rs @@ -4,7 +4,52 @@ use request::{self, FromRequest, Request}; use outcome::Outcome; use http::Status; -// TODO: Doc. +/// Request guard to retrieve managed state. +/// +/// This type can be used as a request guard to retrieve the state Rocket is +/// managing for some type `T`. This allows for the sharing of state across any +/// number of handlers. A value for the given type must previously have been +/// registered to be managed by Rocket via the +/// [manage](/rocket/struct.Rocket.html#method.manage) method. The type being +/// managed must be thread safe and sendable across thread boundaries. In otehr +/// words, it must implement `Send + Sync + 'static`. +/// +/// # Example +/// +/// Imagine you have some configuration struct of the type `MyConfig` that you'd +/// like to initialize at start-up and later access it in several handlers. The +/// following example does just this: +/// +/// ```rust +/// # #![feature(plugin)] +/// # #![plugin(rocket_codegen)] +/// # extern crate rocket; +/// use rocket::State; +/// +/// // In a real application, this would likely be more complex. +/// struct MyConfig(String); +/// +/// #[get("/")] +/// fn index(state: State) -> String { +/// format!("The config value is: {}", state.0) +/// } +/// +/// #[get("/raw")] +/// fn raw_config_value<'r>(state: State<'r, MyConfig>) -> &'r str { +/// // use `inner()` to get a lifetime longer than `deref` gives us +/// state.inner().0.as_str() +/// } +/// +/// fn main() { +/// let config = MyConfig("user input".to_string()); +/// # if false { // We don't actually want to launch the server in an example. +/// rocket::ignite() +/// .mount("/", routes![index, raw_config_value]) +/// .manage(config) +/// .launch() +/// # } +/// } +/// ``` #[derive(Debug, PartialEq, Eq)] pub struct State<'r, T: Send + Sync + 'static>(&'r T); diff --git a/lib/src/rocket.rs b/lib/src/rocket.rs index 200693be..456e0e14 100644 --- a/lib/src/rocket.rs +++ b/lib/src/rocket.rs @@ -513,7 +513,7 @@ impl Rocket { /// rocket::ignite() /// .mount("/", routes![index]) /// .manage(MyValue(10)) - /// # .launch() + /// .launch() /// # } /// } /// ```