ocean.util.aio.JobNotification source code

1 /*******************************************************************************
2 
3     Common interface for various types of suspendable jobs waiting for
4     AsyncIO to finish.
5 
6     Copyright:
7         Copyright (c) 2018 dunnhumby Germany GmbH.
8         All rights reserved.
9 
10     License:
11         Boost Software License Version 1.0. See LICENSE.txt for details.
12 
13 *******************************************************************************/
14 
15 module ocean.util.aio.JobNotification;
16 
17 /// Ditto
18 abstract class JobNotification
19 {
20     import ocean.core.array.Mutation: copy;
21     import ocean.util.aio.internal.JobQueue: Job;
22 
23     /***************************************************************************
24 
25         AsyncIO's method that should be called to discard the results of scheduled
26         asynchronous method.
27 
28     ***************************************************************************/
29 
30     private void delegate(Job*) remove_dg;
31 
32     /***************************************************************************
33 
34         Pointer to the AIO job suspended on this JobNotification.
35         Used for canceling the jobs. TODO: is the closure possible combining
36         remove_dg and job?
37 
38     ***************************************************************************/
39 
40     private Job* job;
41 
42     /***************************************************************************
43 
44         Yields the control to the suspendable job, indicating that the aio
45         operation has been done.
46 
47     ***************************************************************************/
48 
49     protected abstract void wake_ ();
50 
51     /***************************************************************************
52 
53         Cedes the control from the suspendable job, waiting for the aio
54         operation to be done. Implementation is defined by the concrete classes.
55 
56     ***************************************************************************/
57 
58     protected abstract void wait_();
59 
60     /***************************************************************************
61 
62         Cedes the control from the suspendable job, waiting for the aio
63         operation to be done. Called by AsyncIO framework internally.
64 
65         Params:
66             remove_dg = delegate to call to inform AIO that results of this job
67                         can be discarded.
68 
69     ***************************************************************************/
70 
71     public final void wait (Job* job, typeof(this.remove_dg) remove_dg)
72     {
73         scope (failure)
74             this.discardResults();
75 
76         this.register(job, remove_dg);
77         this.wait_();
78     }
79 
80     /**************************************************************************
81 
82         Registers the Job instance with this job notification and sets up
83         removal delegate.
84 
85         Params:
86             job = instance of the job that this job notification is waiting on
87             remove_dg = delegate to call to inform AIO that results of this job
88                         can be discarded.
89 
90     ***************************************************************************/
91 
92     public final void register (Job* job, typeof(this.remove_dg) remove_dg)
93     {
94         this.job = job;
95         this.remove_dg = remove_dg;
96     }
97 
98     /***************************************************************************
99 
100         Detaches the Job instance from this JobNotification (the opposite of
101         register).
102 
103     ***************************************************************************/
104 
105     public final void unregister ()
106     {
107         this.job = null;
108     }
109 
110     /***************************************************************************
111 
112         Yields the control to the suspended job, indicating that the aio
113         operation has been done. Called by the AsyncIO framework internally.
114 
115     ***************************************************************************/
116 
117     public final void wake ()
118     {
119         this.unregister();
120         this.wake_();
121     }
122 
123     /***************************************************************************
124 
125         Should be called by the concrete classes to inform the AIO that
126         results of this operation are no longer needed.
127 
128     ***************************************************************************/
129 
130     public final void discardResults ()
131     {
132         if (this.job)
133         {
134             this.remove_dg(this.job);
135             this.job = null;
136         }
137     }
138 }