mirror of
https://github.com/xcat2/xNBA.git
synced 2026-05-13 01:44:11 +00:00
Michael Brown
e71b83b22b
We have several types of object interface at present (data-xfer, job control, name resolution), and there is some duplication of functionality between them. For example, job_done(), job_kill() and xfer_close() are almost isomorphic to each other. This updated version of the object interface mechanism allows for each interface to export an arbitrary list of supported operations. Advantages include: Operations methods now receive a pointer to the object, rather than a pointer to the interface. This allows an object to, for example, implement a single close() method that can handle close() operations from any of its exposed interfaces. The close() operation is implemented as a generic operation (rather than having specific variants for data-xfer, job control, etc.). This will allow functions such as monojob_wait() to be used to wait for e.g. a name resolution to complete. The amount of boilerplate code required in objects is reduced, not least because it is no longer necessary to include per-interface methods that simply use container_of() to derive a pointer to the object and then tail-call to a common per-object method. The cost of adding new operations is reduced; adding a new data-xfer operation such as stat() no longer incurs the penalty of adding a .stat member to the operations table of all existing data-xfer interfaces. The data-xfer, job control and name resolution interfaces have not yet been updated to use the new interface mechanism, but the code will still compile and run. Signed-off-by: Michael Brown <mcb30@ipxe.org>
170 lines
4.2 KiB
C
170 lines
4.2 KiB
C
#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 ) {
|
|
intf_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 ) {
|
|
intf_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 ) {
|
|
intf_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 */
|