diff options
Diffstat (limited to 'src/include/ipxe/job.h')
-rw-r--r-- | src/include/ipxe/job.h | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/src/include/ipxe/job.h b/src/include/ipxe/job.h new file mode 100644 index 0000000..893a790 --- /dev/null +++ b/src/include/ipxe/job.h @@ -0,0 +1,169 @@ +#ifndef _IPXE_JOB_H +#define _IPXE_JOB_H + +/** @file + * + * Job control interfaces + * + */ + +FILE_LICENCE ( GPL2_OR_LATER ); + +#include <stddef.h> +#include <ipxe/interface.h> + +/** Job progress */ +struct job_progress { + /** Amount of operation completed so far + * + * The units for this quantity are arbitrary. @c completed + * divded by @total should give something which approximately + * represents the progress through the operation. For a + * download operation, using byte counts would make sense. + */ + unsigned long completed; + /** Total operation size + * + * See @c completed. A zero value means "total size unknown" + * and is explcitly permitted; users should take this into + * account before calculating @c completed/total. + */ + unsigned long total; +}; + +struct job_interface; + +/** Job control interface operations */ +struct job_interface_operations { + /** Job completed + * + * @v job Job control interface + * @v rc Overall job status code + */ + void ( * done ) ( struct job_interface *job, int rc ); + /** Abort job + * + * @v job Job control interface + */ + void ( * kill ) ( struct job_interface *job ); + /** Get job progress + * + * @v job Job control interface + * @v progress Progress data to fill in + */ + void ( * progress ) ( struct job_interface *job, + struct job_progress *progress ); +}; + +/** A job control interface */ +struct job_interface { + /** Generic object communication interface */ + struct interface intf; + /** Operations for received messages */ + struct job_interface_operations *op; +}; + +extern struct job_interface null_job; +extern struct job_interface_operations null_job_ops; + +extern void job_done ( struct job_interface *job, int rc ); +extern void job_kill ( struct job_interface *job ); +extern void job_progress ( struct job_interface *job, + struct job_progress *progress ); + +extern void ignore_job_done ( struct job_interface *job, int rc ); +extern void ignore_job_kill ( struct job_interface *job ); +extern void ignore_job_progress ( struct job_interface *job, + struct job_progress *progress ); + +/** + * Initialise a job control interface + * + * @v job Job control interface + * @v op Job control interface operations + * @v refcnt Containing object reference counter, or NULL + */ +static inline void job_init ( struct job_interface *job, + struct job_interface_operations *op, + struct refcnt *refcnt ) { + job->intf.dest = &null_job.intf; + job->intf.refcnt = refcnt; + job->op = op; +} + +/** + * Get job control interface from generic object communication interface + * + * @v intf Generic object communication interface + * @ret job Job control interface + */ +static inline __attribute__ (( always_inline )) struct job_interface * +intf_to_job ( struct interface *intf ) { + return container_of ( intf, struct job_interface, intf ); +} + +/** + * Get reference to destination job control interface + * + * @v job Job control interface + * @ret dest Destination interface + */ +static inline __attribute__ (( always_inline )) struct job_interface * +job_get_dest ( struct job_interface *job ) { + return intf_to_job ( intf_get ( job->intf.dest ) ); +} + +/** + * Drop reference to job control interface + * + * @v job Job control interface + */ +static inline __attribute__ (( always_inline )) void +job_put ( struct job_interface *job ) { + intf_put ( &job->intf ); +} + +/** + * Plug a job control interface into a new destination interface + * + * @v job Job control interface + * @v dest New destination interface + */ +static inline void job_plug ( struct job_interface *job, + struct job_interface *dest ) { + plug ( &job->intf, &dest->intf ); +} + +/** + * Plug two job control interfaces together + * + * @v a Job control interface A + * @v b Job control interface B + */ +static inline void job_plug_plug ( struct job_interface *a, + struct job_interface *b ) { + plug_plug ( &a->intf, &b->intf ); +} + +/** + * Unplug a job control interface + * + * @v job Job control interface + */ +static inline void job_unplug ( struct job_interface *job ) { + plug ( &job->intf, &null_job.intf ); +} + +/** + * Stop using a job control interface + * + * @v job Job control interface + * + * After calling this method, no further messages will be received via + * the interface. + */ +static inline void job_nullify ( struct job_interface *job ) { + job->op = &null_job_ops; +}; + +#endif /* _IPXE_JOB_H */ |