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 */
job_init(struct job_interface * job,struct job_interface_operations * op,struct refcnt * refcnt)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 *
intf_to_job(struct interface * intf)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 *
job_get_dest(struct job_interface * job)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
job_put(struct job_interface * job)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 */
job_plug(struct job_interface * job,struct job_interface * dest)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 */
job_plug_plug(struct job_interface * a,struct job_interface * b)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 */
job_unplug(struct job_interface * job)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 */
job_nullify(struct job_interface * job)165 static inline void job_nullify ( struct job_interface *job ) {
166 job->op = &null_job_ops;
167 };
168
169 #endif /* _GPXE_JOB_H */
170