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 */