Macro incremental_query::define_query

macro_rules! define_query {
    (
        $(
            $(#[$($attr: tt)*])*

            fn $name: ident <$lt: lifetime>
            ($cxname: ident: &Context<$lt2: lifetime> $(,$paramname: ident: &$param: ty)* $(,)?)
            $(-> $ret: ty)?
            $block: block
        )*
    ) => { ... };
}

A macro to define a query.

A query is a lot like a function, except for the small detail that you cannot call it. Instead queries expand to an identifier you can pass to a Context through which you can execute the function.

The following example should illustrate its syntax pretty well:

define_query! {
    // note: the lifetime <'cx> is required, (though you can choose a different name)
    fn some_query<'cx>(
        // this first parameter is required! though you can change the name it gets.
        cx: &Context<'cx>,
        // any number of parameters can follow, but they *must* be of type
        // &T where T: QueryParameter.
        param1: &u64, param2: &u64, param3: &u64) -> u64 {
        // ...
    }

    // more queries can follow
}

The output and input of queries are cached, and its dependencies are automatically tracked.

To run a query, including all the cache mechanics, simply call it. The only requirement is that you give it an argument of &Context<'cx>. Internally, the function you wrote is actually wrapped in such a way that caching can occur.

define_query! {
    fn some_query<'cx>(cx: &Context<'cx>, param1: &u64, param2: &u64, param3: &u64) -> u64 {
        // ...
    }
}

let storage = Storage::new();

let cx = Context::new(&storage);
let output = some_query(&cx, param1, param2, param3);

again, here some_query refers to the query that has to be run. It’s definiton (using define_query)