(index<- ) ./libarena/lib.rs
git branch: * master 5200215 auto merge of #14035 : alexcrichton/rust/experimental, r=huonw
modified: Fri May 9 13:02:28 2014
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 //! The arena, a fast but limited type of allocator.
12 //!
13 //! Arenas are a type of allocator that destroy the objects within, all at
14 //! once, once the arena itself is destroyed. They do not support deallocation
15 //! of individual objects while the arena itself is still alive. The benefit
16 //! of an arena is very fast allocation; just a pointer bump.
17
18 #![crate_id = "arena#0.11-pre"]
19 #![crate_type = "rlib"]
20 #![crate_type = "dylib"]
21 #![license = "MIT/ASL2"]
22 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
23 html_favicon_url = "http://www.rust-lang.org/favicon.ico",
24 html_root_url = "http://static.rust-lang.org/doc/master")]
25 #![allow(missing_doc)]
26
27 extern crate collections;
28
29 use std::cast::{transmute, transmute_mut_lifetime};
30 use std::cast;
31 use std::cell::{Cell, RefCell};
32 use std::cmp;
33 use std::intrinsics::{TyDesc, get_tydesc};
34 use std::intrinsics;
35 use std::mem;
36 use std::num;
37 use std::ptr::read;
38 use std::rc::Rc;
39 use std::rt::global_heap;
40
41 // The way arena uses arrays is really deeply awful. The arrays are
42 // allocated, and have capacities reserved, but the fill for the array
43 // will always stay at 0.
44 #[deriving(Clone, Eq)]
45 struct Chunk {
46 data: Rc<RefCell<Vec<u8> >>,
47 fill: Cell<uint>,
48 is_copy: Cell<bool>,
49 }
50 impl Chunk {
51 fn capacity(&self) -> uint {
52 self.data.borrow().capacity()
53 }
54
55 unsafe fn as_ptr(&self) -> *u8 {
56 self.data.borrow().as_ptr()
57 }
58 }
59
60 // Arenas are used to quickly allocate objects that share a
61 // lifetime. The arena uses ~[u8] vectors as a backing store to
62 // allocate objects from. For each allocated object, the arena stores
63 // a pointer to the type descriptor followed by the
64 // object. (Potentially with alignment padding after each of them.)
65 // When the arena is destroyed, it iterates through all of its chunks,
66 // and uses the tydesc information to trace through the objects,
67 // calling the destructors on them.
68 // One subtle point that needs to be addressed is how to handle
69 // failures while running the user provided initializer function. It
70 // is important to not run the destructor on uninitialized objects, but
71 // how to detect them is somewhat subtle. Since alloc() can be invoked
72 // recursively, it is not sufficient to simply exclude the most recent
73 // object. To solve this without requiring extra space, we use the low
74 // order bit of the tydesc pointer to encode whether the object it
75 // describes has been fully initialized.
76
77 // As an optimization, objects with destructors are stored in
78 // different chunks than objects without destructors. This reduces
79 // overhead when initializing plain-old-data and means we don't need
80 // to waste time running the destructors of POD.
81 pub struct Arena {
82 // The head is separated out from the list as a unbenchmarked
83 // microoptimization, to avoid needing to case on the list to
84 // access the head.
85 head: Chunk,
86 copy_head: Chunk,
87 chunks: RefCell<Vec<Chunk>>,
88 }
89
90 impl Arena {
91 pub fn new() -> Arena {
92 Arena::new_with_size(32u)
93 }
94
95 pub fn new_with_size(initial_size: uint) -> Arena {
96 Arena {
97 head: chunk(initial_size, false),
98 copy_head: chunk(initial_size, true),
99 chunks: RefCell::new(Vec::new()),
100 }
101 }
102 }
103
104 fn chunk(size: uint, is_copy: bool) -> Chunk {
105 Chunk {
106 data: Rc::new(RefCell::new(Vec::with_capacity(size))),
107 fill: Cell::new(0u),
108 is_copy: Cell::new(is_copy),
109 }
110 }
111
112 #[unsafe_destructor]
113 impl Drop for Arena {
114 fn drop(&mut self) {
115 unsafe {
116 destroy_chunk(&self.head);
117 for chunk in self.chunks.borrow().iter() {
118 if !chunk.is_copy.get() {
119 destroy_chunk(chunk);
120 }
121 }
122 }
123 }
124 }
125
126 #[inline]
127 fn round_up(base: uint, align: uint) -> uint {
128 (base.checked_add(&(align - 1))).unwrap() & !(&(align - 1))
129 }
130
131 // Walk down a chunk, running the destructors for any objects stored
132 // in it.
133 unsafe fn destroy_chunk(chunk: &Chunk) {
134 let mut idx = 0;
135 let buf = chunk.as_ptr();
136 let fill = chunk.fill.get();
137
138 while idx < fill {
139 let tydesc_data: *uint = transmute(buf.offset(idx as int));
140 let (tydesc, is_done) = un_bitpack_tydesc_ptr(*tydesc_data);
141 let (size, align) = ((*tydesc).size, (*tydesc).align);
142
143 let after_tydesc = idx + mem::size_of::<*TyDesc>();
144
145 let start = round_up(after_tydesc, align);
146
147 //debug!("freeing object: idx = {}, size = {}, align = {}, done = {}",
148 // start, size, align, is_done);
149 if is_done {
150 ((*tydesc).drop_glue)(buf.offset(start as int) as *i8);
151 }
152
153 // Find where the next tydesc lives
154 idx = round_up(start + size, mem::pref_align_of::<*TyDesc>());
155 }
156 }
157
158 // We encode whether the object a tydesc describes has been
159 // initialized in the arena in the low bit of the tydesc pointer. This
160 // is necessary in order to properly do cleanup if a failure occurs
161 // during an initializer.
162 #[inline]
163 fn bitpack_tydesc_ptr(p: *TyDesc, is_done: bool) -> uint {
164 p as uint | (is_done as uint)
165 }
166 #[inline]
167 fn un_bitpack_tydesc_ptr(p: uint) -> (*TyDesc, bool) {
168 ((p & !1) as *TyDesc, p & 1 == 1)
169 }
170
171 impl Arena {
172 fn chunk_size(&self) -> uint {
173 self.copy_head.capacity()
174 }
175 // Functions for the POD part of the arena
176 fn alloc_copy_grow(&mut self, n_bytes: uint, align: uint) -> *u8 {
177 // Allocate a new chunk.
178 let new_min_chunk_size = cmp::max(n_bytes, self.chunk_size());
179 self.chunks.borrow_mut().push(self.copy_head.clone());
180 self.copy_head =
181 chunk(num::next_power_of_two(new_min_chunk_size + 1u), true);
182
183 return self.alloc_copy_inner(n_bytes, align);
184 }
185
186 #[inline]
187 fn alloc_copy_inner(&mut self, n_bytes: uint, align: uint) -> *u8 {
188 unsafe {
189 let this = transmute_mut_lifetime(self);
190 let start = round_up(this.copy_head.fill.get(), align);
191 let end = start + n_bytes;
192 if end > self.chunk_size() {
193 return this.alloc_copy_grow(n_bytes, align);
194 }
195 this.copy_head.fill.set(end);
196
197 //debug!("idx = {}, size = {}, align = {}, fill = {}",
198 // start, n_bytes, align, head.fill.get());
199
200 this.copy_head.as_ptr().offset(start as int)
201 }
202 }
203
204 #[inline]
205 fn alloc_copy<'a, T>(&'a mut self, op: || -> T) -> &'a T {
206 unsafe {
207 let ptr = self.alloc_copy_inner(mem::size_of::<T>(), mem::min_align_of::<T>());
208 let ptr: *mut T = transmute(ptr);
209 mem::move_val_init(&mut (*ptr), op());
210 return transmute(ptr);
211 }
212 }
213
214 // Functions for the non-POD part of the arena
215 fn alloc_noncopy_grow(&mut self, n_bytes: uint, align: uint)
216 -> (*u8, *u8) {
217 // Allocate a new chunk.
218 let new_min_chunk_size = cmp::max(n_bytes, self.chunk_size());
219 self.chunks.borrow_mut().push(self.head.clone());
220 self.head =
221 chunk(num::next_power_of_two(new_min_chunk_size + 1u), false);
222
223 return self.alloc_noncopy_inner(n_bytes, align);
224 }
225
226 #[inline]
227 fn alloc_noncopy_inner(&mut self, n_bytes: uint, align: uint)
228 -> (*u8, *u8) {
229 unsafe {
230 let start;
231 let end;
232 let tydesc_start;
233 let after_tydesc;
234
235 {
236 let head = transmute_mut_lifetime(&mut self.head);
237
238 tydesc_start = head.fill.get();
239 after_tydesc = head.fill.get() + mem::size_of::<*TyDesc>();
240 start = round_up(after_tydesc, align);
241 end = start + n_bytes;
242 }
243
244 if end > self.head.capacity() {
245 return self.alloc_noncopy_grow(n_bytes, align);
246 }
247
248 let head = transmute_mut_lifetime(&mut self.head);
249 head.fill.set(round_up(end, mem::pref_align_of::<*TyDesc>()));
250
251 //debug!("idx = {}, size = {}, align = {}, fill = {}",
252 // start, n_bytes, align, head.fill);
253
254 let buf = self.head.as_ptr();
255 return (buf.offset(tydesc_start as int), buf.offset(start as int));
256 }
257 }
258
259 #[inline]
260 fn alloc_noncopy<'a, T>(&'a mut self, op: || -> T) -> &'a T {
261 unsafe {
262 let tydesc = get_tydesc::<T>();
263 let (ty_ptr, ptr) =
264 self.alloc_noncopy_inner(mem::size_of::<T>(), mem::min_align_of::<T>());
265 let ty_ptr: *mut uint = transmute(ty_ptr);
266 let ptr: *mut T = transmute(ptr);
267 // Write in our tydesc along with a bit indicating that it
268 // has *not* been initialized yet.
269 *ty_ptr = transmute(tydesc);
270 // Actually initialize it
271 mem::move_val_init(&mut(*ptr), op());
272 // Now that we are done, update the tydesc to indicate that
273 // the object is there.
274 *ty_ptr = bitpack_tydesc_ptr(tydesc, true);
275
276 return transmute(ptr);
277 }
278 }
279
280 // The external interface
281 #[inline]
282 pub fn alloc<'a, T>(&'a self, op: || -> T) -> &'a T {
283 unsafe {
284 // FIXME #13933: Remove/justify all `&T` to `&mut T` transmutes
285 let this: &mut Arena = transmute::<&_, &mut _>(self);
286 if intrinsics::needs_drop::<T>() {
287 this.alloc_noncopy(op)
288 } else {
289 this.alloc_copy(op)
290 }
291 }
292 }
293 }
294
295 #[test]
296 fn test_arena_destructors() {
297 let arena = Arena::new();
298 for i in range(0u, 10) {
299 // Arena allocate something with drop glue to make sure it
300 // doesn't leak.
301 arena.alloc(|| Rc::new(i));
302 // Allocate something with funny size and alignment, to keep
303 // things interesting.
304 arena.alloc(|| [0u8, 1u8, 2u8]);
305 }
306 }
307
308 #[test]
309 #[should_fail]
310 fn test_arena_destructors_fail() {
311 let arena = Arena::new();
312 // Put some stuff in the arena.
313 for i in range(0u, 10) {
314 // Arena allocate something with drop glue to make sure it
315 // doesn't leak.
316 arena.alloc(|| { Rc::new(i) });
317 // Allocate something with funny size and alignment, to keep
318 // things interesting.
319 arena.alloc(|| { [0u8, 1u8, 2u8] });
320 }
321 // Now, fail while allocating
322 arena.alloc::<Rc<int>>(|| {
323 // Now fail.
324 fail!();
325 });
326 }
327
328 /// An arena that can hold objects of only one type.
329 ///
330 /// Safety note: Modifying objects in the arena that have already had their
331 /// `drop` destructors run can cause leaks, because the destructor will not
332 /// run again for these objects.
333 pub struct TypedArena<T> {
334 /// A pointer to the next object to be allocated.
335 ptr: *T,
336
337 /// A pointer to the end of the allocated area. When this pointer is
338 /// reached, a new chunk is allocated.
339 end: *T,
340
341 /// A pointer to the first arena segment.
342 first: Option<Box<TypedArenaChunk<T>>>,
343 }
344
345 struct TypedArenaChunk<T> {
346 /// Pointer to the next arena segment.
347 next: Option<Box<TypedArenaChunk<T>>>,
348
349 /// The number of elements that this chunk can hold.
350 capacity: uint,
351
352 // Objects follow here, suitably aligned.
353 }
354
355 impl<T> TypedArenaChunk<T> {
356 #[inline]
357 fn new(next: Option<Box<TypedArenaChunk<T>>>, capacity: uint)
358 -> Box<TypedArenaChunk<T>> {
359 let mut size = mem::size_of::<TypedArenaChunk<T>>();
360 size = round_up(size, mem::min_align_of::<T>());
361 let elem_size = mem::size_of::<T>();
362 let elems_size = elem_size.checked_mul(&capacity).unwrap();
363 size = size.checked_add(&elems_size).unwrap();
364
365 let mut chunk = unsafe {
366 let chunk = global_heap::exchange_malloc(size);
367 let mut chunk: Box<TypedArenaChunk<T>> = cast::transmute(chunk);
368 mem::move_val_init(&mut chunk.next, next);
369 chunk
370 };
371
372 chunk.capacity = capacity;
373 chunk
374 }
375
376 /// Destroys this arena chunk. If the type descriptor is supplied, the
377 /// drop glue is called; otherwise, drop glue is not called.
378 #[inline]
379 unsafe fn destroy(&mut self, len: uint) {
380 // Destroy all the allocated objects.
381 if intrinsics::needs_drop::<T>() {
382 let mut start = self.start();
383 for _ in range(0, len) {
384 read(start as *T); // run the destructor on the pointer
385 start = start.offset(mem::size_of::<T>() as int)
386 }
387 }
388
389 // Destroy the next chunk.
390 let next_opt = mem::replace(&mut self.next, None);
391 match next_opt {
392 None => {}
393 Some(mut next) => {
394 // We assume that the next chunk is completely filled.
395 next.destroy(next.capacity)
396 }
397 }
398 }
399
400 // Returns a pointer to the first allocated object.
401 #[inline]
402 fn start(&self) -> *u8 {
403 let this: *TypedArenaChunk<T> = self;
404 unsafe {
405 cast::transmute(round_up(this.offset(1) as uint, mem::min_align_of::<T>()))
406 }
407 }
408
409 // Returns a pointer to the end of the allocated space.
410 #[inline]
411 fn end(&self) -> *u8 {
412 unsafe {
413 let size = mem::size_of::<T>().checked_mul(&self.capacity).unwrap();
414 self.start().offset(size as int)
415 }
416 }
417 }
418
419 impl<T> TypedArena<T> {
420 /// Creates a new arena with preallocated space for 8 objects.
421 #[inline]
422 pub fn new() -> TypedArena<T> {
423 TypedArena::with_capacity(8)
424 }
425
426 /// Creates a new arena with preallocated space for the given number of
427 /// objects.
428 #[inline]
429 pub fn with_capacity(capacity: uint) -> TypedArena<T> {
430 let chunk = TypedArenaChunk::<T>::new(None, capacity);
431 TypedArena {
432 ptr: chunk.start() as *T,
433 end: chunk.end() as *T,
434 first: Some(chunk),
435 }
436 }
437
438 /// Allocates an object into this arena.
439 #[inline]
440 pub fn alloc<'a>(&'a self, object: T) -> &'a T {
441 unsafe {
442 // FIXME #13933: Remove/justify all `&T` to `&mut T` transmutes
443 let this: &mut TypedArena<T> = cast::transmute::<&_, &mut _>(self);
444 if this.ptr == this.end {
445 this.grow()
446 }
447
448 let ptr: &'a mut T = cast::transmute(this.ptr);
449 mem::move_val_init(ptr, object);
450 this.ptr = this.ptr.offset(1);
451 let ptr: &'a T = ptr;
452 ptr
453 }
454 }
455
456 /// Grows the arena.
457 #[inline(never)]
458 fn grow(&mut self) {
459 let chunk = self.first.take_unwrap();
460 let new_capacity = chunk.capacity.checked_mul(&2).unwrap();
461 let chunk = TypedArenaChunk::<T>::new(Some(chunk), new_capacity);
462 self.ptr = chunk.start() as *T;
463 self.end = chunk.end() as *T;
464 self.first = Some(chunk)
465 }
466 }
467
468 #[unsafe_destructor]
469 impl<T> Drop for TypedArena<T> {
470 fn drop(&mut self) {
471 // Determine how much was filled.
472 let start = self.first.get_ref().start() as uint;
473 let end = self.ptr as uint;
474 let diff = (end - start) / mem::size_of::<T>();
475
476 // Pass that to the `destroy` method.
477 unsafe {
478 self.first.get_mut_ref().destroy(diff)
479 }
480 }
481 }
482
483 #[cfg(test)]
484 mod tests {
485 extern crate test;
486 use self::test::Bencher;
487 use super::{Arena, TypedArena};
488
489 struct Point {
490 x: int,
491 y: int,
492 z: int,
493 }
494
495 #[test]
496 pub fn test_copy() {
497 let arena = TypedArena::new();
498 for _ in range(0, 100000) {
499 arena.alloc(Point {
500 x: 1,
501 y: 2,
502 z: 3,
503 });
504 }
505 }
506
507 #[bench]
508 pub fn bench_copy(b: &mut Bencher) {
509 let arena = TypedArena::new();
510 b.iter(|| {
511 arena.alloc(Point {
512 x: 1,
513 y: 2,
514 z: 3,
515 })
516 })
517 }
518
519 #[bench]
520 pub fn bench_copy_nonarena(b: &mut Bencher) {
521 b.iter(|| {
522 box Point {
523 x: 1,
524 y: 2,
525 z: 3,
526 }
527 })
528 }
529
530 #[bench]
531 pub fn bench_copy_old_arena(b: &mut Bencher) {
532 let arena = Arena::new();
533 b.iter(|| {
534 arena.alloc(|| {
535 Point {
536 x: 1,
537 y: 2,
538 z: 3,
539 }
540 })
541 })
542 }
543
544 struct Noncopy {
545 string: ~str,
546 array: Vec<int> ,
547 }
548
549 #[test]
550 pub fn test_noncopy() {
551 let arena = TypedArena::new();
552 for _ in range(0, 100000) {
553 arena.alloc(Noncopy {
554 string: "hello world".to_owned(),
555 array: vec!( 1, 2, 3, 4, 5 ),
556 });
557 }
558 }
559
560 #[bench]
561 pub fn bench_noncopy(b: &mut Bencher) {
562 let arena = TypedArena::new();
563 b.iter(|| {
564 arena.alloc(Noncopy {
565 string: "hello world".to_owned(),
566 array: vec!( 1, 2, 3, 4, 5 ),
567 })
568 })
569 }
570
571 #[bench]
572 pub fn bench_noncopy_nonarena(b: &mut Bencher) {
573 b.iter(|| {
574 box Noncopy {
575 string: "hello world".to_owned(),
576 array: vec!( 1, 2, 3, 4, 5 ),
577 }
578 })
579 }
580
581 #[bench]
582 pub fn bench_noncopy_old_arena(b: &mut Bencher) {
583 let arena = Arena::new();
584 b.iter(|| {
585 arena.alloc(|| Noncopy {
586 string: "hello world".to_owned(),
587 array: vec!( 1, 2, 3, 4, 5 ),
588 })
589 })
590 }
591 }
libarena/lib.rs:344:1-344:1 -struct- definition:
struct TypedArenaChunk<T> {
/// Pointer to the next arena segment.
next: Option<Box<TypedArenaChunk<T>>>,
references:- 8341: /// A pointer to the first arena segment.
342: first: Option<Box<TypedArenaChunk<T>>>,
343: }
--
358: -> Box<TypedArenaChunk<T>> {
359: let mut size = mem::size_of::<TypedArenaChunk<T>>();
360: size = round_up(size, mem::min_align_of::<T>());
--
366: let chunk = global_heap::exchange_malloc(size);
367: let mut chunk: Box<TypedArenaChunk<T>> = cast::transmute(chunk);
368: mem::move_val_init(&mut chunk.next, next);
--
402: fn start(&self) -> *u8 {
403: let this: *TypedArenaChunk<T> = self;
404: unsafe {
libarena/lib.rs:126:10-126:10 -fn- definition:
fn round_up(base: uint, align: uint) -> uint {
(base.checked_add(&(align - 1))).unwrap() & !(&(align - 1))
}
references:- 7145: let start = round_up(after_tydesc, align);
--
153: // Find where the next tydesc lives
154: idx = round_up(start + size, mem::pref_align_of::<*TyDesc>());
155: }
--
359: let mut size = mem::size_of::<TypedArenaChunk<T>>();
360: size = round_up(size, mem::min_align_of::<T>());
361: let elem_size = mem::size_of::<T>();
--
404: unsafe {
405: cast::transmute(round_up(this.offset(1) as uint, mem::min_align_of::<T>()))
406: }
libarena/lib.rs:332:33-332:33 -struct- definition:
/// run again for these objects.
pub struct TypedArena<T> {
/// A pointer to the next object to be allocated.
references:- 6430: let chunk = TypedArenaChunk::<T>::new(None, capacity);
431: TypedArena {
432: ptr: chunk.start() as *T,
--
442: // FIXME #13933: Remove/justify all `&T` to `&mut T` transmutes
443: let this: &mut TypedArena<T> = cast::transmute::<&_, &mut _>(self);
444: if this.ptr == this.end {
--
469: impl<T> Drop for TypedArena<T> {
470: fn drop(&mut self) {
libarena/lib.rs:44:23-44:23 -struct- definition:
struct Chunk {
data: Rc<RefCell<Vec<u8> >>,
fill: Cell<uint>,
references:- 1843: // will always stay at 0.
45: struct Chunk {
--
104: fn chunk(size: uint, is_copy: bool) -> Chunk {
105: Chunk {
106: data: Rc::new(RefCell::new(Vec::with_capacity(size))),
--
132: // in it.
133: unsafe fn destroy_chunk(chunk: &Chunk) {
134: let mut idx = 0;
libarena/lib.rs:132:10-132:10 -fn- definition:
// in it.
unsafe fn destroy_chunk(chunk: &Chunk) {
let mut idx = 0;
references:- 2118: if !chunk.is_copy.get() {
119: destroy_chunk(chunk);
120: }
libarena/lib.rs:80:49-80:49 -struct- definition:
// to waste time running the destructors of POD.
pub struct Arena {
// The head is separated out from the list as a unbenchmarked
references:- 795: pub fn new_with_size(initial_size: uint) -> Arena {
96: Arena {
97: head: chunk(initial_size, false),
--
284: // FIXME #13933: Remove/justify all `&T` to `&mut T` transmutes
285: let this: &mut Arena = transmute::<&_, &mut _>(self);
286: if intrinsics::needs_drop::<T>() {
libarena/lib.rs:103:1-103:1 -fn- definition:
fn chunk(size: uint, is_copy: bool) -> Chunk {
Chunk {
data: Rc::new(RefCell::new(Vec::with_capacity(size))),
references:- 4220: self.head =
221: chunk(num::next_power_of_two(new_min_chunk_size + 1u), false);