Home | History | Annotate | Download | only in gpxe 
      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 */
    170