1 // Copyright 2013 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
4 //
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
10
11 /*!
12 The Finally trait provides a method, `finally` on
13 stack closures that emulates Java-style try/finally blocks.
14
15 Using the `finally` method is sometimes convenient, but the type rules
16 prohibit any shared, mutable state between the "try" case and the
17 "finally" case. For advanced cases, the `try_finally` function can
18 also be used. See that function for more details.
19
20 # Example
21
22 ```
23 use std::unstable::finally::Finally;
24
25 (|| {
26 // ...
27 }).finally(|| {
28 // this code is always run
29 })
30 ```
31 */
32
33 use ops::Drop;
34
35 #[cfg(test)] use task::failing;
36
37 pub trait Finally<T> {
38 fn finally(&self, dtor: ||) -> T;
39 }
40
41 impl<'a,T> Finally<T> for ||: 'a -> T {
42 fn finally(&self, dtor: ||) -> T {
43 try_finally(&mut (), (),
44 |_, _| (*self)(),
45 |_| dtor())
46 }
47 }
48
49 impl<T> Finally<T> for fn() -> T {
50 fn finally(&self, dtor: ||) -> T {
51 try_finally(&mut (), (),
52 |_, _| (*self)(),
53 |_| dtor())
54 }
55 }
56
57 /**
58 * The most general form of the `finally` functions. The function
59 * `try_fn` will be invoked first; whether or not it fails, the
60 * function `finally_fn` will be invoked next. The two parameters
61 * `mutate` and `drop` are used to thread state through the two
62 * closures. `mutate` is used for any shared, mutable state that both
63 * closures require access to; `drop` is used for any state that the
64 * `try_fn` requires ownership of.
65 *
66 * **WARNING:** While shared, mutable state between the try and finally
67 * function is often necessary, one must be very careful; the `try`
68 * function could have failed at any point, so the values of the shared
69 * state may be inconsistent.
70 *
71 * # Example
72 *
73 * ```
74 * use std::unstable::finally::try_finally;
75 *
76 * struct State<'a> { buffer: &'a mut [u8], len: uint }
77 * # let mut buf = [];
78 * let mut state = State { buffer: buf, len: 0 };
79 * try_finally(
80 * &mut state, (),
81 * |state, ()| {
82 * // use state.buffer, state.len
83 * },
84 * |state| {
85 * // use state.buffer, state.len to cleanup
86 * })
87 * ```
88 */
89 pub fn try_finally<T,U,R>(mutate: &mut T,
90 drop: U,
91 try_fn: |&mut T, U| -> R,
92 finally_fn: |&mut T|)
93 -> R {
94 let f = Finallyalizer {
95 mutate: mutate,
96 dtor: finally_fn,
97 };
98 try_fn(&mut *f.mutate, drop)
99 }
100
101 struct Finallyalizer<'a,A> {
102 mutate: &'a mut A,
103 dtor: |&mut A|: 'a
104 }
105
106 #[unsafe_destructor]
107 impl<'a,A> Drop for Finallyalizer<'a,A> {
108 #[inline]
109 fn drop(&mut self) {
110 (self.dtor)(self.mutate);
111 }
112 }
113
114 #[test]
115 fn test_success() {
116 let mut i = 0;
117 try_finally(
118 &mut i, (),
119 |i, ()| {
120 *i = 10;
121 },
122 |i| {
123 assert!(!failing());
124 assert_eq!(*i, 10);
125 *i = 20;
126 });
127 assert_eq!(i, 20);
128 }
129
130 #[test]
131 #[should_fail]
132 fn test_fail() {
133 let mut i = 0;
134 try_finally(
135 &mut i, (),
136 |i, ()| {
137 *i = 10;
138 fail!();
139 },
140 |i| {
141 assert!(failing());
142 assert_eq!(*i, 10);
143 })
144 }
145
146 #[test]
147 fn test_retval() {
148 let closure: || -> int = || 10;
149 let i = closure.finally(|| { });
150 assert_eq!(i, 10);
151 }
152
153 #[test]
154 fn test_compact() {
155 fn do_some_fallible_work() {}
156 fn but_always_run_this_function() { }
157 do_some_fallible_work.finally(
158 but_always_run_this_function);
159 }
libstd/unstable/finally.rs:100:1-100:1 -struct- definition:
struct Finallyalizer<'a,A> {
mutate: &'a mut A,
dtor: |&mut A|: 'a
references:- 293: -> R {
94: let f = Finallyalizer {
95: mutate: mutate,
--
107: impl<'a,A> Drop for Finallyalizer<'a,A> {
108: #[inline]
libstd/unstable/finally.rs:36:1-36:1 -trait- definition:
pub trait Finally<T> {
fn finally(&self, dtor: ||) -> T;
}
references:- 249: impl<T> Finally<T> for fn() -> T {
50: fn finally(&self, dtor: ||) -> T {
libstd/unstable/finally.rs:88:4-88:4 -fn- definition:
*/
pub fn try_finally<T,U,R>(mutate: &mut T,
drop: U,
references:- 450: fn finally(&self, dtor: ||) -> T {
51: try_finally(&mut (), (),
52: |_, _| (*self)(),
libstd/slice.rs:
667: // inside the loop stops LLVM from optimising this.
668: try_finally(
669: &mut i, (),
libstd/io/mod.rs:
510: try_finally(
511: &mut s, (),
libstd/unstable/finally.rs:
42: fn finally(&self, dtor: ||) -> T {
43: try_finally(&mut (), (),
44: |_, _| (*self)(),