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