AcquiredSingleton

Singleton (per-execution context) acquired resource of the templated type. An external source of elements of this type -- a FreeList!(T) -- is required. When the singleton resource is acquired (via the acquire() method), it is requested from the free list and stored internally. All subsequent calls to acquire() return the same instance. When the resource is no longer required, the relinquish() method will return it to the free list.

struct AcquiredSingleton (

) {

import ocean.util.container.pool.FreeList;;

alias Elem = T*;

alias Elem = T;

void initialise(FreeList!(T) t_pool);

Elem acquire(Elem new_t);

Elem acquire(Elem new_t, void delegate(Elem) reset);

void relinquish();

}

Members

Aliases

Elem alias Elem = T*: Type of a new resource. (Differs for reference / value types.)
Elem alias Elem = T: Undocumented in source.

Functions

acquire Elem acquire(Elem new_t): Gets the singleton T instance.
acquire Elem acquire(Elem new_t, void delegate(Elem) reset): Gets the singleton T instance.
initialise void initialise(FreeList!(T) t_pool): Initialises this instance. (No other methods may be called before calling this method.)
relinquish void relinquish(): Relinquishes singleton shared resources acquired by this instance.

Parameters

T: type of resource

Examples

1 // Type of a specialised resource which may be required by an execution
2 // context.
3 struct MyResource
4 {
5 }
6 
7 // Demonstrates how a typical global shared resources container should look.
8 // A single instance of this would be owned at the top level of the app.
9 class SharedResources
10 {
11     import ocean.util.container.pool.FreeList;
12 
13     // The pool of specialised resources required by AcquiredSingleton.
14     private FreeList!(MyResource) myresources;
15 
16     this ( )
17     {
18         this.myresources = new FreeList!(MyResource);
19     }
20 
21     // Objects of this class will be newed at scope and passed to execution
22     // contexts. This allows the context to acquire various shared resources
23     // and have them automatically relinquished when it exits.
24     class ContextResources
25     {
26         // Tracker of the singleton resource acquired by the context.
27         private AcquiredSingleton!(MyResource) myresource_singleton;
28 
29         // Initialise the tracker in the ctor.
30         this ( )
31         {
32             this.myresource_singleton.initialise(this.outer.myresources);
33         }
34 
35         // ...and be sure to relinquish all the acquired resources in the
36         // dtor.
37         ~this ( )
38         {
39             this.myresource_singleton.relinquish();
40         }
41 
42         // Public method to get the resource singleton for this execution
43         // context, managed by the tracker.
44         public MyResource* myResource ( )
45         {
46             return this.myresource_singleton.acquire(new MyResource,
47                 ( MyResource* resource )
48                 {
49                     // When the singleton is first acquired, perform any
50                     // logic required to reset it to its initial state.
51                     *resource = MyResource.init;
52                 }
53             );
54         }
55     }
56 }
57 
58 // Demonstrates the usage of the shared resources and the context resources.
59 class Context
60 {
61     SharedResources resources;
62 
63     void entryPoint ( )
64     {
65         // New a ContextResources as scope, so that its dtor will be called
66         // at scope exit and all acquired resources relinquished.
67         scope acquired = this.resources.new ContextResources;
68 
69         // Acquire a resource.
70         acquired.myResource();
71 
72         // Acquire the same resource again.
73         acquired.myResource();
74     }
75 }