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         /** Job completed
  37          *
  38          * @v job               Job control interface
  39          * @v rc                Overall job status code
  40          */
  41         void ( * done ) ( struct job_interface *job, int rc );
  42         /** Abort job
  43          *
  44          * @v job               Job control interface
  45          */
  46         void ( * kill ) ( struct job_interface *job );
  47         /** Get job progress
  48          *
  49          * @v job               Job control interface
  50          * @v progress          Progress data to fill in
  51          */
  52         void ( * progress ) ( struct job_interface *job,
  53                               struct job_progress *progress );
  54 };
  55
  56 /** A job control interface */
  57 struct job_interface {
  58         /** Generic object communication interface */
  59         struct interface intf;
  60         /** Operations for received messages */
  61         struct job_interface_operations *op;
  62 };
  63
  64 extern struct job_interface null_job;
  65 extern struct job_interface_operations null_job_ops;
  66
  67 extern void job_done ( struct job_interface *job, int rc );
  68
  69 extern void ignore_job_done ( struct job_interface *job, int rc );
  70 extern void ignore_job_kill ( struct job_interface *job );
  71 extern void ignore_job_progress ( struct job_interface *job,
  72                                   struct job_progress *progress );
  73
  74 /**
  75  * Initialise a job control interface
  76  *
  77  * @v job               Job control interface
  78  * @v op                Job control interface operations
  79  * @v refcnt            Containing object reference counter, or NULL
  80  */
  81 static inline void job_init ( struct job_interface *job,
  82                               struct job_interface_operations *op,
  83                               struct refcnt *refcnt ) {
  84         job->intf.dest = &null_job.intf;
  85         job->intf.refcnt = refcnt;
  86         job->op = op;
  87 }
  88
  89 /**
  90  * Get job control interface from generic object communication interface
  91  *
  92  * @v intf              Generic object communication interface
  93  * @ret job             Job control interface
  94  */
  95 static inline __attribute__ (( always_inline )) struct job_interface *
  96 intf_to_job ( struct interface *intf ) {
  97         return container_of ( intf, struct job_interface, intf );
  98 }
  99
 100 /**
 101  * Get reference to destination job control interface
 102  *
 103  * @v job               Job control interface
 104  * @ret dest            Destination interface
 105  */
 106 static inline __attribute__ (( always_inline )) struct job_interface *
 107 job_get_dest ( struct job_interface *job ) {
 108         return intf_to_job ( intf_get ( job->intf.dest ) );
 109 }
 110
 111 /**
 112  * Drop reference to job control interface
 113  *
 114  * @v job               Job control interface
 115  */
 116 static inline __attribute__ (( always_inline )) void
 117 job_put ( struct job_interface *job ) {
 118         intf_put ( &job->intf );
 119 }
 120
 121 /**
 122  * Plug a job control interface into a new destination interface
 123  *
 124  * @v job               Job control interface
 125  * @v dest              New destination interface
 126  */
 127 static inline void job_plug ( struct job_interface *job,
 128                                struct job_interface *dest ) {
 129         plug ( &job->intf, &dest->intf );
 130 }
 131
 132 /**
 133  * Plug two job control interfaces together
 134  *
 135  * @v a                 Job control interface A
 136  * @v b                 Job control interface B
 137  */
 138 static inline void job_plug_plug ( struct job_interface *a,
 139                                     struct job_interface *b ) {
 140         plug_plug ( &a->intf, &b->intf );
 141 }
 142
 143 /**
 144  * Unplug a job control interface
 145  *
 146  * @v job               Job control interface
 147  */
 148 static inline void job_unplug ( struct job_interface *job ) {
 149         plug ( &job->intf, &null_job.intf );
 150 }
 151
 152 /**
 153  * Stop using a job control interface
 154  *
 155  * @v job               Job control interface
 156  *
 157  * After calling this method, no further messages will be received via
 158  * the interface.
 159  */
 160 static inline void job_nullify ( struct job_interface *job ) {
 161         job->op = &null_job_ops;
 162 };
 163
 164 #endif /* _GPXE_JOB_H */