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 done ( struct job_interface *job, int rc );
  68
  69 extern void ignore_done ( struct job_interface *job, int rc );
  70 extern void ignore_kill ( struct job_interface *job );
  71 extern void ignore_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            Job control interface reference counting method
  80  */
  81 static inline void job_init ( struct job_interface *job,
  82                                struct job_interface_operations *op,
  83                                void ( * refcnt ) ( struct interface *intf,
  84                                                    int delta ) ) {
  85         job->intf.dest = &null_job.intf;
  86         job->intf.refcnt = refcnt;
  87         job->op = op;
  88 }
  89
  90 /**
  91  * Get job control interface from generic object communication interface
  92  *
  93  * @v intf              Generic object communication interface
  94  * @ret job             Job control interface
  95  */
  96 static inline struct job_interface *
  97 intf_to_job ( struct interface *intf ) {
  98         return container_of ( intf, struct job_interface, intf );
  99 }
 100
 101 /**
 102  * Get destination job control interface
 103  *
 104  * @v job               Job control interface
 105  * @ret dest            Destination interface
 106  */
 107 static inline struct job_interface *
 108 job_dest ( struct job_interface *job ) {
 109         return intf_to_job ( job->intf.dest );
 110 }
 111
 112 /**
 113  * Stop using a job control interface
 114  *
 115  * @v job               Job control interface
 116  *
 117  * After calling this method, no further messages will be received via
 118  * the interface.
 119  */
 120 static inline void job_nullify ( struct job_interface *job ) {
 121         job->op = &null_job_ops;
 122 };
 123
 124 #endif /* _GPXE_JOB_H */