Do not hold self-references. This then avoids the problem of having to
[people/dverkamp/gpxe.git] / src / include / gpxe / job.h
1 #ifndef _GPXE_JOB_H
2 #define _GPXE_JOB_H
3
4 /** @file
5  *
6  * Job control interfaces
7  *
8  */
9
10 #include <stddef.h>
11 #include <gpxe/interface.h>
12
13 /** Job progress */
14 struct job_progress {
15         /** Amount of operation completed so far
16          *
17          * The units for this quantity are arbitrary.  @c completed
18          * divded by @total should give something which approximately
19          * represents the progress through the operation.  For a
20          * download operation, using byte counts would make sense.
21          */
22         unsigned long completed;
23         /** Total operation size
24          *
25          * See @c completed.  A zero value means "total size unknown"
26          * and is explcitly permitted; users should take this into
27          * account before calculating @c completed/total.
28          */
29         unsigned long total;
30 };
31
32 struct job_interface;
33
34 /** Job control interface operations */
35 struct job_interface_operations {
36         /** Start job
37          *
38          * @v job               Job control interface
39          */
40         void ( * start ) ( struct job_interface *job );
41         /** Job completed
42          *
43          * @v job               Job control interface
44          * @v rc                Overall job status code
45          */
46         void ( * done ) ( struct job_interface *job, int rc );
47         /** Abort job
48          *
49          * @v job               Job control interface
50          */
51         void ( * kill ) ( struct job_interface *job );
52         /** Get job progress
53          *
54          * @v job               Job control interface
55          * @v progress          Progress data to fill in
56          */
57         void ( * progress ) ( struct job_interface *job,
58                               struct job_progress *progress );
59 };
60
61 /** A job control interface */
62 struct job_interface {
63         /** Generic object communication interface */
64         struct interface intf;
65         /** Operations for received messages */
66         struct job_interface_operations *op;
67 };
68
69 extern struct job_interface null_job;
70 extern struct job_interface_operations null_job_ops;
71
72 extern void job_done ( struct job_interface *job, int rc );
73
74 extern void ignore_job_start ( struct job_interface *job );
75 extern void ignore_job_done ( struct job_interface *job, int rc );
76 extern void ignore_job_kill ( struct job_interface *job );
77 extern void ignore_job_progress ( struct job_interface *job,
78                                   struct job_progress *progress );
79
80 /**
81  * Initialise a job control interface
82  *
83  * @v job               Job control interface
84  * @v op                Job control interface operations
85  * @v refcnt            Containing object reference counter, or NULL
86  */
87 static inline void job_init ( struct job_interface *job,
88                               struct job_interface_operations *op,
89                               struct refcnt *refcnt ) {
90         job->intf.dest = &null_job.intf;
91         job->intf.refcnt = refcnt;
92         job->op = op;
93 }
94
95 /**
96  * Get job control interface from generic object communication interface
97  *
98  * @v intf              Generic object communication interface
99  * @ret job             Job control interface
100  */
101 static inline __attribute__ (( always_inline )) struct job_interface *
102 intf_to_job ( struct interface *intf ) {
103         return container_of ( intf, struct job_interface, intf );
104 }
105
106 /**
107  * Get reference to destination job control interface
108  *
109  * @v job               Job control interface
110  * @ret dest            Destination interface
111  */
112 static inline __attribute__ (( always_inline )) struct job_interface *
113 job_get_dest ( struct job_interface *job ) {
114         return intf_to_job ( intf_get ( job->intf.dest ) );
115 }
116
117 /**
118  * Drop reference to job control interface
119  *
120  * @v job               Job control interface
121  */
122 static inline __attribute__ (( always_inline )) void
123 job_put ( struct job_interface *job ) {
124         intf_put ( &job->intf );
125 }
126
127 /**
128  * Plug a job control interface into a new destination interface
129  *
130  * @v job               Job control interface
131  * @v dest              New destination interface
132  */
133 static inline void job_plug ( struct job_interface *job,
134                                struct job_interface *dest ) {
135         plug ( &job->intf, &dest->intf );
136 }
137
138 /**
139  * Plug two job control interfaces together
140  *
141  * @v a                 Job control interface A
142  * @v b                 Job control interface B
143  */
144 static inline void job_plug_plug ( struct job_interface *a,
145                                     struct job_interface *b ) {
146         plug_plug ( &a->intf, &b->intf );
147 }
148
149 /**
150  * Unplug a job control interface
151  *
152  * @v job               Job control interface
153  */
154 static inline void job_unplug ( struct job_interface *job ) {
155         plug ( &job->intf, &null_job.intf );
156 }
157
158 /**
159  * Stop using a job control interface
160  *
161  * @v job               Job control interface
162  *
163  * After calling this method, no further messages will be received via
164  * the interface.
165  */
166 static inline void job_nullify ( struct job_interface *job ) {
167         job->op = &null_job_ops;
168 };
169
170 #endif /* _GPXE_JOB_H */