automem source code

1 /**
2 C++-style automatic memory management smart pointers for D using `stdx.allocator`.
3 
4 Unlike the C++ variants, the smart pointers themselves allocate the memory for the objects they contain.
5 That ensures the right allocator is used to dispose of the memory as well.
6 
7 Allocators are template arguments instead of using `theAllocator` so
8 that these smart pointers can be used in `@nogc` code. However, they
9 will default to `typeof(theAllocator)` for simplicity. The examples
10 above will be explicit.
11 
12 Another reason to have to pass in the type of allocator is to decide how it is to
13 be stored. Stateless allocators can be "stored" by value and imply zero-cost `Unique` pointers.
14 Singleton allocators such as Mallocator (that have an `instance` attribute/member function)
15 don't need to be passed in to the constructor. This is detected at compile-time as an example
16 of design by instrospection.
17 
18 `RefCounted` leverages D's type system by doing atomic reference counting *iff* the type of the contained
19 object is `shared`. Otherwise it's non-atomic.
20 */
21 module automem;
22 
23 public import automem.unique;
24 public import automem.ref_counted;
25 public import automem.vector;
26 public import automem.array;
27 
28 
29 // This unittest can be @safe if the allocator has @safe functions
30 @system unittest {
31 
32     import std.algorithm: move;
33 
34     static struct Point {
35         int x;
36         int y;
37     }
38 
39     // set theAllocator as desired beforehand, e.g.
40     // theAllocator = allocatorObject(Mallocator.instance)
41 
42     {
43         // must pass arguments to initialise the contained object
44         auto u1 = Unique!Point(2, 3);
45         assert(*u1 == Point(2, 3));
46         assert(u1.y == 3);
47 
48         // auto u2 = u1; // won't compile, can only move
49         typeof(u1) u2 = u1.move;
50         assert(cast(bool)u1 == false); // u1 is now empty
51     }
52     // memory freed for the Point structure created in the block
53 
54     {
55         auto s1 = RefCounted!Point(4, 5);
56         assert(*s1 == Point(4, 5));
57         assert(s1.x == 4);
58         {
59             auto s2 = s1; // can be copied
60         } // ref count goes to 1 here
61 
62     } // ref count goes to 0 here, memory released
63 
64     {
65         import std.algorithm: map;
66         import std.range: iota;
67 
68         // `vector` is also known as `array`
69         auto vec = vector(Point(1, 2), Point(3, 4), Point(5, 6));
70         assert(vec[] == [Point(1, 2), Point(3, 4), Point(5, 6)]);
71 
72         vec.length = 1;
73         assert(vec[] == [Point(1, 2)]);
74 
75         vec ~= Point(7, 8);
76         assert(vec[] == [Point(1, 2), Point(7, 8)]);
77 
78         vec ~= 2.iota.map!(i => Point(i + 10, i + 11));
79         assert(vec[] == [Point(1, 2), Point(7, 8), Point(10, 11), Point(11, 12)]);
80     } // memory for the array released here
81 }
82 
83 
84 // @nogc test - must explicitly use the allocator for compile-time guarantees
85 @system @nogc unittest {
86     import stdx.allocator.mallocator: Mallocator;
87 
88     static struct Point {
89         int x;
90         int y;
91     }
92 
93     {
94         // must pass arguments to initialise the contained object
95         auto u1 = Unique!(Point, Mallocator)(2, 3);
96         assert(*u1 == Point(2, 3));
97         assert(u1.y == 3);
98     }
99     // memory freed for the Point structure created in the block
100 
101     // similarly for the other types
102 }