1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
/*!
A macro for defining cached/memoized functions that wrap a static-ref cache object.
**Note:** Due to the requirements of storing arguments and return values in a global cache,
function arguments and return types must be owned, function arguments must implement `Hash + Eq + Clone`,
and function return types must implement `Clone`.
Arguments and return values will be cloned in the process of insertion and retrieval.
`cached!` functions should not be used to produce side-effectual results!
# Usage & Options:
There's several options depending on how explicit you want to be. See below for full syntax breakdown.
1.) Use an explicitly specified cache-type and provide the instantiated cache struct.
For example, a `SizedCache` (LRU).
```rust,no_run
#[macro_use] extern crate cached;
#[macro_use] extern crate lazy_static;
use cached::SizedCache;
cached!{FIB: SizedCache = SizedCache::with_capacity(50); >>
fn fib(n: u64) -> u64 = {
if n == 0 || n == 1 { return n }
fib(n-1) + fib(n-2)
}}
# pub fn main() { }
```
2.) Use an explicitly specified cache-type, but let the macro instantiate it.
The cache-type is expected to have a `new` method that takes no arguments.
```rust,no_run
#[macro_use] extern crate cached;
#[macro_use] extern crate lazy_static;
use cached::UnboundCache;
cached!{FIB: UnboundCache >>
fn fib(n: u64) -> u64 = {
if n == 0 || n == 1 { return n }
fib(n-1) + fib(n-2)
}}
# pub fn main() { }
```
3.) Use the default unbounded cache.
```rust,no_run
#[macro_use] extern crate cached;
#[macro_use] extern crate lazy_static;
cached!{FIB >>
fn fib(n: u64) -> u64 = {
if n == 0 || n == 1 { return n }
fib(n-1) + fib(n-2)
}}
# pub fn main() { }
```
# Cache Types
Several caches are available in this crate:
- `cached::UnboundCache`
- `cached::SizedCache`
- `cached::TimedCache`
Any custom cache that implements `cached::Cached` can be used in place of the built-ins.
# Syntax:
The complete macro syntax is:
```rust,ignore
cached!{CACHE_NAME: CacheType = CacheType::constructor(arg); >>
fn func_name(arg1: arg_type, arg2: arg_type) -> return_type = {
// do stuff like normal
return_type
}}
```
Where:
- `CACHE_NAME` is the unique name used to hold a `static ref` to the cache
- `CacheType` is the struct type to use for the cache (Note, this cannot be namespaced, e.g.
`cached::SizedCache` will not be accepted by the macro. `SizedCache` must be imported and passed
directly)
- `CacheType::constructor(arg)` is any expression that yields an instance of `CacheType` to be used
as the cache-store, followed by `; >>`
- `fn func_name(arg1: arg_type) -> return_type` is the same form as a regular function signature, with the exception
that functions with no return value must be explicitly stated (e.g. `fn func_name(arg: arg_type) -> ()`)
- The expression following `=` is the function body assigned to `func_name`. Note, the function
body can make recursive calls to its cached-self (`func_name`).
*/
pub use *;
/// Cache operations