https://github.com/appcypher/lazy-attribute
Convenient attribute macro for lazy function execution
https://github.com/appcypher/lazy-attribute
crate docs function lazy-evaluation proc-macro-attributes rust
Last synced: 4 months ago
JSON representation
Convenient attribute macro for lazy function execution
- Host: GitHub
- URL: https://github.com/appcypher/lazy-attribute
- Owner: appcypher
- License: apache-2.0
- Created: 2023-10-30T07:05:22.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-08T08:42:08.000Z (almost 2 years ago)
- Last Synced: 2026-01-14T01:34:15.514Z (5 months ago)
- Topics: crate, docs, function, lazy-evaluation, proc-macro-attributes, rust
- Language: Rust
- Homepage:
- Size: 108 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE-APACHE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
lazy-attribute
`lazy-attributes` provides attribute macros for simplifying working with lazily evaluated functions.
Functions decorated with `#[lazy_ref]` will only be executed the first time they are called.
On subsequent calls, the cached return value is returned.
## Outline
- [Usage](#usage)
- [Contributing](#contributing)
- [Getting Help](#getting-help)
- [External Resources](#external-resources)
- [License](#license)
## Usage
Add this to your `Cargo.toml`:
```toml
[dependencies]
lazy-attribute = "0.1"
```
### Examples
With [`lazy_attribute::lazy_ref`][crate::lazy_ref], you can annotate a function that you want to lazily evaluate:
```rust
use lazy_attribute::lazy_ref;
#[lazy_ref]
fn get_string() -> String {
println!("Called once!");
String::from("Hello, world!")
}
fn main() {
println!("{}", get_string()); // Outputs: Called once! Hello, world!
println!("{}", get_string()); // Outputs: Hello, world!
}
```
The first time the function is called, it will be evaluated and its result will be cached. Subsequent calls will return
the cached result.
`lazy_ref` macro roughly desugars the `get_string` function to:
```ignore
static __lazy_static_get_string: OnceCell = OnceCell::new();
fn get_string() -> &'static String {
__lazy_static_get_string.get_or_init(|| {
println!("Called once!");
String::from("Hello, world!")
})
}
```
With `async` feature enabled, `lazy_ref` can also be used with async functions:
```rust
use lazy_attribute::lazy_ref;
#[lazy_ref]
async fn get_string() -> String {
println!("Called once!");
String::from("Hello, world!")
}
#[tokio::main]
async fn main() {
println!("{}", get_string().await); // Outputs: Called once! Hello, world!
println!("{}", get_string().await); // Outputs: Hello, world!
}
```
## Caveats
- `lazy_*` macros do not support functions with arguments. You will get an error telling you arguments are not supported.
## Crate Features
- `async` - Enables support for lazily evaluating async functions.
### Crate Features
- `async` - Enables support for lazily evaluating async functions.
## Contributing
Feedback welcome! Check the [contributing guide](./CONTRIBUTING.md) to you want to get involved. We
also adhere to our [Code of Conduct](./CODE_OF_CONDUCT.md).
### Testing the Project
- Run tests
```console
cargo test --all-features
```
### Formatting
For formatting Rust in particular, please use `cargo +nightly fmt` as it uses
specific nightly features we recommend. **Make sure you have nightly
installed**.
### Pre-commit Hook
This project recommends using [pre-commit][pre-commit] for running pre-commit
hooks. Please run this before every commit and/or push.
- Once installed, Run `pre-commit install` and `pre-commit install --hook-type commit-msg`
to setup the pre-commit hooks locally. This will reduce failed CI builds.
- If you are doing interim commits locally, and for some reason if you _don't_
want pre-commit hooks to fire, you can run
`git commit -a -m "Your message here" --no-verify`.
## License
This project is licensed under either of
- Apache License, Version 2.0, ([LICENSE-APACHE](./LICENSE-APACHE) or [http://www.apache.org/licenses/LICENSE-2.0][apache])
- MIT license ([LICENSE-MIT](./LICENSE-MIT) or [http://opensource.org/licenses/MIT][mit])
at your option.
### Contribution
Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the Apache-2.0
license, shall be dual licensed as above, without any additional terms or
conditions.
[apache]: https://www.apache.org/licenses/LICENSE-2.0
[cargo-expand]: https://github.com/dtolnay/cargo-expand
[cargo-udeps]: https://github.com/est31/cargo-udeps
[cargo-watch]: https://github.com/watchexec/cargo-watch
[commit-spec]: https://www.conventionalcommits.org/en/v1.0.0/#specification
[commit-spec-site]: https://www.conventionalcommits.org/
[irust]: https://github.com/sigmaSd/IRust
[mit]: http://opensource.org/licenses/MIT
[pre-commit]: https://pre-commit.com/
[crate::lazy_ref]: https://docs.rs/lazy-attribute/latest/lazy_attribute/attr.lazy_ref.html