[interface] Expand object interface to allow for polymorphic interfaces
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>
This commit is contained in:
parent
5fa6775b61
commit
e71b83b22b
|
@ -18,19 +18,42 @@
|
|||
|
||||
FILE_LICENCE ( GPL2_OR_LATER );
|
||||
|
||||
#include <string.h>
|
||||
#include <ipxe/interface.h>
|
||||
|
||||
/** @file
|
||||
*
|
||||
* Object communication interfaces
|
||||
* Object interfaces
|
||||
*
|
||||
*/
|
||||
|
||||
/*****************************************************************************
|
||||
*
|
||||
* The null interface
|
||||
*
|
||||
*/
|
||||
|
||||
/** Null interface operations */
|
||||
static struct interface_operation null_intf_op[] = {};
|
||||
|
||||
/** Null interface descriptor */
|
||||
struct interface_descriptor null_intf_desc =
|
||||
INTF_DESC_PURE ( null_intf_op );
|
||||
|
||||
/** The null interface */
|
||||
struct interface null_intf = INTF_INIT ( null_intf_desc );
|
||||
|
||||
/*****************************************************************************
|
||||
*
|
||||
* Object interface plumbing
|
||||
*
|
||||
*/
|
||||
|
||||
/**
|
||||
* Plug an interface into a new destination interface
|
||||
* Plug an object interface into a new destination object interface
|
||||
*
|
||||
* @v intf Interface
|
||||
* @v dest New destination interface
|
||||
* @v intf Object interface
|
||||
* @v dest New destination object interface
|
||||
*
|
||||
* The reference to the existing destination interface is dropped, a
|
||||
* reference to the new destination interface is obtained, and the
|
||||
|
@ -39,24 +62,209 @@ FILE_LICENCE ( GPL2_OR_LATER );
|
|||
* Note that there is no "unplug" call; instead you must plug the
|
||||
* interface into a null interface.
|
||||
*/
|
||||
void plug ( struct interface *intf, struct interface *dest ) {
|
||||
DBGC ( intf, "INTF %p moving from INTF %p to INTF %p\n",
|
||||
intf, intf->dest, dest );
|
||||
void intf_plug ( struct interface *intf, struct interface *dest ) {
|
||||
DBGC ( INTF_COL ( intf ),
|
||||
"INTF " INTF_INTF_FMT " replug to " INTF_FMT "\n",
|
||||
INTF_INTF_DBG ( intf, intf->dest ), INTF_DBG ( dest ) );
|
||||
intf_get ( dest );
|
||||
intf_put ( intf->dest );
|
||||
intf->dest = intf_get ( dest );
|
||||
intf->dest = dest;
|
||||
}
|
||||
|
||||
/**
|
||||
* Plug two interfaces together
|
||||
* Plug two object interfaces together
|
||||
*
|
||||
* @v a Interface A
|
||||
* @v b Interface B
|
||||
* @v a Object interface A
|
||||
* @v b Object interface B
|
||||
*
|
||||
* Plugs interface A into interface B, and interface B into interface
|
||||
* A. (The basic plug() function is unidirectional; this function is
|
||||
* merely a shorthand for two calls to plug(), hence the name.)
|
||||
*/
|
||||
void plug_plug ( struct interface *a, struct interface *b ) {
|
||||
plug ( a, b );
|
||||
plug ( b, a );
|
||||
void intf_plug_plug ( struct interface *a, struct interface *b ) {
|
||||
intf_plug ( a, b );
|
||||
intf_plug ( b, a );
|
||||
}
|
||||
|
||||
/**
|
||||
* Unplug an object interface
|
||||
*
|
||||
* @v intf Object interface
|
||||
*/
|
||||
void intf_unplug ( struct interface *intf ) {
|
||||
intf_plug ( intf, &null_intf );
|
||||
}
|
||||
|
||||
/**
|
||||
* Ignore all further operations on an object interface
|
||||
*
|
||||
* @v intf Object interface
|
||||
*/
|
||||
void intf_nullify ( struct interface *intf ) {
|
||||
intf->desc = &null_intf_desc;
|
||||
}
|
||||
|
||||
/**
|
||||
* Increment reference count on an object interface
|
||||
*
|
||||
* @v intf Object interface
|
||||
* @ret intf Object interface
|
||||
*/
|
||||
struct interface * intf_get ( struct interface *intf ) {
|
||||
ref_get ( intf->refcnt );
|
||||
return intf;
|
||||
}
|
||||
|
||||
/**
|
||||
* Decrement reference count on an object interface
|
||||
*
|
||||
* @v intf Object interface
|
||||
*/
|
||||
void intf_put ( struct interface *intf ) {
|
||||
ref_put ( intf->refcnt );
|
||||
}
|
||||
|
||||
/**
|
||||
* Get pointer to object containing object interface
|
||||
*
|
||||
* @v intf Object interface
|
||||
* @ret object Containing object
|
||||
*/
|
||||
void * intf_object ( struct interface *intf ) {
|
||||
return ( ( ( void * ) intf ) - intf->desc->offset );
|
||||
}
|
||||
|
||||
/**
|
||||
* Get pass-through interface
|
||||
*
|
||||
* @v intf Object interface
|
||||
* @ret passthru Pass-through interface, or NULL
|
||||
*/
|
||||
static struct interface * intf_get_passthru ( struct interface *intf ) {
|
||||
struct interface_descriptor *desc = intf->desc;
|
||||
|
||||
if ( desc->passthru_offset ) {
|
||||
return ( ( ( void * ) intf ) + desc->passthru_offset );
|
||||
} else {
|
||||
return NULL;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get object interface destination and operation method
|
||||
*
|
||||
* @v intf Object interface
|
||||
* @v type Operation type
|
||||
* @ret dest Destination interface
|
||||
* @ret func Implementing method, or NULL
|
||||
*/
|
||||
void * intf_get_dest_op_untyped ( struct interface *intf, void *type,
|
||||
struct interface **dest ) {
|
||||
struct interface_descriptor *desc;
|
||||
struct interface_operation *op;
|
||||
unsigned int i;
|
||||
|
||||
while ( 1 ) {
|
||||
/* Search for an implementing method provided by the
|
||||
* current destination interface.
|
||||
*/
|
||||
*dest = intf_get ( intf->dest );
|
||||
desc = (*dest)->desc;
|
||||
for ( i = desc->num_op, op = desc->op ; i ; i--, op++ ) {
|
||||
if ( op->type == type )
|
||||
return op->func;
|
||||
}
|
||||
|
||||
/* Pass through to the underlying interface, if applicable */
|
||||
if ( ! ( intf = intf_get_passthru ( *dest ) ) )
|
||||
return NULL;
|
||||
intf_put ( *dest );
|
||||
}
|
||||
}
|
||||
|
||||
/*****************************************************************************
|
||||
*
|
||||
* Generic interface operations
|
||||
*
|
||||
*/
|
||||
|
||||
/**
|
||||
* Close an object interface
|
||||
*
|
||||
* @v intf Object interface
|
||||
* @v rc Reason for close
|
||||
*
|
||||
* Note that this function merely informs the destination object that
|
||||
* the interface is about to be closed; it doesn't actually disconnect
|
||||
* the interface. In most cases, you probably want to use
|
||||
* intf_shutdown() or intf_restart() instead.
|
||||
*/
|
||||
void intf_close ( struct interface *intf, int rc ) {
|
||||
struct interface *dest;
|
||||
intf_close_TYPE ( void * ) *op =
|
||||
intf_get_dest_op ( intf, intf_close, &dest );
|
||||
void *object = intf_object ( dest );
|
||||
|
||||
DBGC ( INTF_COL ( intf ), "INTF " INTF_INTF_FMT " close (%s)\n",
|
||||
INTF_INTF_DBG ( intf, dest ), strerror ( rc ) );
|
||||
|
||||
if ( op ) {
|
||||
op ( object, rc );
|
||||
} else {
|
||||
/* Default is to ignore intf_close() */
|
||||
}
|
||||
|
||||
intf_put ( dest );
|
||||
}
|
||||
|
||||
/**
|
||||
* Shut down an object interface
|
||||
*
|
||||
* @v intf Object interface
|
||||
* @v rc Reason for close
|
||||
*
|
||||
* Blocks further operations from being received via the interface,
|
||||
* executes a close operation on the destination interface, and
|
||||
* unplugs the interface.
|
||||
*/
|
||||
void intf_shutdown ( struct interface *intf, int rc ) {
|
||||
|
||||
DBGC ( INTF_COL ( intf ), "INTF " INTF_FMT " shutting down (%s)\n",
|
||||
INTF_DBG ( intf ), strerror ( rc ) );
|
||||
|
||||
/* Block further operations */
|
||||
intf_nullify ( intf );
|
||||
|
||||
/* Notify destination of close */
|
||||
intf_close ( intf, rc );
|
||||
|
||||
/* Unplug interface */
|
||||
intf_unplug ( intf );
|
||||
}
|
||||
|
||||
/**
|
||||
* Shut down and restart an object interface
|
||||
*
|
||||
* @v intf Object interface
|
||||
* @v rc Reason for close
|
||||
*
|
||||
* Shuts down the interface, then unblocks operations that were
|
||||
* blocked during shutdown.
|
||||
*/
|
||||
void intf_restart ( struct interface *intf, int rc ) {
|
||||
struct interface_descriptor *desc = intf->desc;
|
||||
|
||||
/* Shut down the interface */
|
||||
intf_shutdown ( intf, rc );
|
||||
|
||||
DBGC ( INTF_COL ( intf ), "INTF " INTF_FMT " restarting\n",
|
||||
INTF_DBG ( intf ) );
|
||||
|
||||
/* Restore the interface descriptor. Must be done after
|
||||
* shutdown (rather than inhibiting intf_shutdown() from
|
||||
* nullifying the descriptor) in order to avoid a potential
|
||||
* infinite loop as the intf_close() operations on each side
|
||||
* of the link call each other recursively.
|
||||
*/
|
||||
intf->desc = desc;
|
||||
}
|
||||
|
|
|
@ -3,23 +3,116 @@
|
|||
|
||||
/** @file
|
||||
*
|
||||
* Object communication interfaces
|
||||
* Object interfaces
|
||||
*
|
||||
*/
|
||||
|
||||
FILE_LICENCE ( GPL2_OR_LATER );
|
||||
|
||||
#include <stddef.h>
|
||||
#include <ipxe/refcnt.h>
|
||||
|
||||
/** An object communication interface */
|
||||
/** An object interface operation */
|
||||
struct interface_operation {
|
||||
/** Operation type */
|
||||
void *type;
|
||||
/** Implementing method */
|
||||
void *func;
|
||||
};
|
||||
|
||||
/**
|
||||
* Define an object interface operation
|
||||
*
|
||||
* @v op_type Operation type
|
||||
* @v object_type Implementing method's expected object type
|
||||
* @v op_func Implementing method
|
||||
* @ret op Object interface operation
|
||||
*/
|
||||
#define INTF_OP( op_type, object_type, op_func ) { \
|
||||
.type = op_type, \
|
||||
.func = ( ( ( ( typeof ( op_func ) * ) NULL ) == \
|
||||
( ( op_type ## _TYPE ( object_type ) * ) NULL ) ) \
|
||||
? op_func : op_func ), \
|
||||
}
|
||||
|
||||
/** An object interface descriptor */
|
||||
struct interface_descriptor {
|
||||
/** Offset of interface within containing object */
|
||||
size_t offset;
|
||||
/** Number of interface operations */
|
||||
unsigned int num_op;
|
||||
/** Object interface operations */
|
||||
struct interface_operation *op;
|
||||
/** Offset to pass-through interface, if present */
|
||||
ssize_t passthru_offset;
|
||||
};
|
||||
|
||||
#define intf_offset( object_type, intf ) \
|
||||
( ( ( ( typeof ( ( ( object_type * ) NULL )->intf ) * ) NULL ) \
|
||||
== ( ( struct interface * ) NULL ) ) \
|
||||
? offsetof ( object_type, intf ) \
|
||||
: offsetof ( object_type, intf ) )
|
||||
|
||||
/**
|
||||
* Define an object interface descriptor
|
||||
*
|
||||
* @v object_type Containing object data type
|
||||
* @v intf Interface name (i.e. field within object data type)
|
||||
* @v operations Object interface operations array
|
||||
* @ret desc Object interface descriptor
|
||||
*/
|
||||
#define INTF_DESC( object_type, intf, operations ) { \
|
||||
.offset = intf_offset ( object_type, intf ), \
|
||||
.op = operations, \
|
||||
.num_op = ( sizeof ( operations ) / \
|
||||
sizeof ( operations[0] ) ), \
|
||||
.passthru_offset = 0, \
|
||||
}
|
||||
|
||||
/**
|
||||
* Define an object interface descriptor with pass-through interface
|
||||
*
|
||||
* @v object_type Containing object data type
|
||||
* @v intf Interface name (i.e. field within object data type)
|
||||
* @v operations Object interface operations array
|
||||
* @v passthru Pass-through interface name
|
||||
* @ret desc Object interface descriptor
|
||||
*/
|
||||
#define INTF_DESC_PASSTHRU( object_type, intf, operations, passthru ) { \
|
||||
.offset = offsetof ( object_type, intf ), \
|
||||
.op = operations, \
|
||||
.num_op = ( sizeof ( operations ) / \
|
||||
sizeof ( operations[0] ) ), \
|
||||
.passthru_offset = ( intf_offset ( object_type, passthru ) - \
|
||||
intf_offset ( object_type, intf ) ), \
|
||||
}
|
||||
|
||||
/**
|
||||
* Define an object interface descriptor for a pure-interface object
|
||||
*
|
||||
* @v operations Object interface operations array
|
||||
* @ret desc Object interface descriptor
|
||||
*
|
||||
* A pure-interface object is an object that consists solely of a
|
||||
* single interface.
|
||||
*/
|
||||
#define INTF_DESC_PURE( operations ) { \
|
||||
.offset = 0, \
|
||||
.op = operations, \
|
||||
.num_op = ( sizeof ( operations ) / \
|
||||
sizeof ( operations[0] ) ), \
|
||||
.passthru_offset = 0, \
|
||||
}
|
||||
|
||||
/** An object interface */
|
||||
struct interface {
|
||||
/** Destination interface
|
||||
/** Destination object interface
|
||||
*
|
||||
* When messages are sent via this interface, they will be
|
||||
* delivered to the destination interface.
|
||||
* When the containing object invokes an operation on this
|
||||
* interface, it will be executed by the destination object.
|
||||
*
|
||||
* This pointer may never be NULL. When the interface is
|
||||
* unplugged, it should point to a null interface.
|
||||
* unplugged, it should point to the null interface.
|
||||
*/
|
||||
struct interface *dest;
|
||||
/** Reference counter
|
||||
|
@ -28,31 +121,99 @@ struct interface {
|
|||
* object, this field may be NULL.
|
||||
*/
|
||||
struct refcnt *refcnt;
|
||||
/** Interface descriptor */
|
||||
struct interface_descriptor *desc;
|
||||
};
|
||||
|
||||
extern void intf_plug ( struct interface *intf, struct interface *dest );
|
||||
extern void intf_plug_plug ( struct interface *a, struct interface *b );
|
||||
extern void intf_unplug ( struct interface *intf );
|
||||
extern void intf_nullify ( struct interface *intf );
|
||||
extern struct interface * intf_get ( struct interface *intf );
|
||||
extern void intf_put ( struct interface *intf );
|
||||
extern void * __attribute__ (( pure )) intf_object ( struct interface *intf );
|
||||
extern void * intf_get_dest_op_untyped ( struct interface *intf, void *type,
|
||||
struct interface **dest );
|
||||
|
||||
extern void intf_close ( struct interface *intf, int rc );
|
||||
#define intf_close_TYPE( object_type ) \
|
||||
typeof ( void ( object_type, int rc ) )
|
||||
|
||||
extern void intf_shutdown ( struct interface *intf, int rc );
|
||||
extern void intf_restart ( struct interface *intf, int rc );
|
||||
|
||||
extern struct interface_descriptor null_intf_desc;
|
||||
extern struct interface null_intf;
|
||||
|
||||
/**
|
||||
* Increment reference count on an interface
|
||||
* Initialise an object interface
|
||||
*
|
||||
* @v intf Interface
|
||||
* @ret intf Interface
|
||||
* @v intf Object interface
|
||||
* @v desc Object interface descriptor
|
||||
* @v refcnt Containing object reference counter, or NULL
|
||||
*/
|
||||
static inline __attribute__ (( always_inline )) struct interface *
|
||||
intf_get ( struct interface *intf ) {
|
||||
ref_get ( intf->refcnt );
|
||||
return intf;
|
||||
static inline void intf_init ( struct interface *intf,
|
||||
struct interface_descriptor *desc,
|
||||
struct refcnt *refcnt ) {
|
||||
intf->dest = &null_intf;
|
||||
intf->refcnt = refcnt;
|
||||
intf->desc = desc;
|
||||
}
|
||||
|
||||
/**
|
||||
* Decrement reference count on an interface
|
||||
* Initialise a static object interface
|
||||
*
|
||||
* @v intf Interface
|
||||
* @v descriptor Object interface descriptor
|
||||
*/
|
||||
static inline __attribute__ (( always_inline )) void
|
||||
intf_put ( struct interface *intf ) {
|
||||
ref_put ( intf->refcnt );
|
||||
}
|
||||
#define INTF_INIT( descriptor ) { \
|
||||
.dest = &null_intf, \
|
||||
.refcnt = NULL, \
|
||||
.desc = &(descriptor), \
|
||||
}
|
||||
|
||||
extern void plug ( struct interface *intf, struct interface *dest );
|
||||
extern void plug_plug ( struct interface *a, struct interface *b );
|
||||
/**
|
||||
* Get object interface destination and operation method
|
||||
*
|
||||
* @v intf Object interface
|
||||
* @v type Operation type
|
||||
* @ret dest Destination interface
|
||||
* @ret func Implementing method, or NULL
|
||||
*/
|
||||
#define intf_get_dest_op( intf, type, dest ) \
|
||||
( ( type ## _TYPE ( void * ) * ) \
|
||||
intf_get_dest_op_untyped ( intf, type, dest ) )
|
||||
|
||||
/**
|
||||
* Find debugging colourisation for an object interface
|
||||
*
|
||||
* @v intf Object interface
|
||||
* @ret col Debugging colourisation
|
||||
*
|
||||
* Use as the first argument to DBGC() or equivalent macro.
|
||||
*/
|
||||
#define INTF_COL( intf ) intf_object ( intf )
|
||||
|
||||
/** printf() format string for INTF_DBG() */
|
||||
#define INTF_FMT "%p+%zx"
|
||||
|
||||
/**
|
||||
* printf() arguments for representing an object interface
|
||||
*
|
||||
* @v intf Object interface
|
||||
* @ret args printf() argument list corresponding to INTF_FMT
|
||||
*/
|
||||
#define INTF_DBG( intf ) intf_object ( intf ), (intf)->desc->offset
|
||||
|
||||
/** printf() format string for INTF_INTF_DBG() */
|
||||
#define INTF_INTF_FMT INTF_FMT "->" INTF_FMT
|
||||
|
||||
/**
|
||||
* printf() arguments for representing an object interface pair
|
||||
*
|
||||
* @v intf Object interface
|
||||
* @v dest Destination object interface
|
||||
* @ret args printf() argument list corresponding to INTF_INTF_FMT
|
||||
*/
|
||||
#define INTF_INTF_DBG( intf, dest ) INTF_DBG ( intf ), INTF_DBG ( dest )
|
||||
|
||||
#endif /* _IPXE_INTERFACE_H */
|
||||
|
|
|
@ -131,7 +131,7 @@ job_put ( struct job_interface *job ) {
|
|||
*/
|
||||
static inline void job_plug ( struct job_interface *job,
|
||||
struct job_interface *dest ) {
|
||||
plug ( &job->intf, &dest->intf );
|
||||
intf_plug ( &job->intf, &dest->intf );
|
||||
}
|
||||
|
||||
/**
|
||||
|
@ -142,7 +142,7 @@ static inline void job_plug ( struct job_interface *job,
|
|||
*/
|
||||
static inline void job_plug_plug ( struct job_interface *a,
|
||||
struct job_interface *b ) {
|
||||
plug_plug ( &a->intf, &b->intf );
|
||||
intf_plug_plug ( &a->intf, &b->intf );
|
||||
}
|
||||
|
||||
/**
|
||||
|
@ -151,7 +151,7 @@ static inline void job_plug_plug ( struct job_interface *a,
|
|||
* @v job Job control interface
|
||||
*/
|
||||
static inline void job_unplug ( struct job_interface *job ) {
|
||||
plug ( &job->intf, &null_job.intf );
|
||||
intf_plug ( &job->intf, &null_job.intf );
|
||||
}
|
||||
|
||||
/**
|
||||
|
|
|
@ -94,7 +94,7 @@ resolv_put ( struct resolv_interface *resolv ) {
|
|||
*/
|
||||
static inline __attribute__ (( always_inline )) void
|
||||
resolv_plug ( struct resolv_interface *resolv, struct resolv_interface *dest ) {
|
||||
plug ( &resolv->intf, &dest->intf );
|
||||
intf_plug ( &resolv->intf, &dest->intf );
|
||||
}
|
||||
|
||||
/**
|
||||
|
@ -105,7 +105,7 @@ resolv_plug ( struct resolv_interface *resolv, struct resolv_interface *dest ) {
|
|||
*/
|
||||
static inline __attribute__ (( always_inline )) void
|
||||
resolv_plug_plug ( struct resolv_interface *a, struct resolv_interface *b ) {
|
||||
plug_plug ( &a->intf, &b->intf );
|
||||
intf_plug_plug ( &a->intf, &b->intf );
|
||||
}
|
||||
|
||||
/**
|
||||
|
@ -115,7 +115,7 @@ resolv_plug_plug ( struct resolv_interface *a, struct resolv_interface *b ) {
|
|||
*/
|
||||
static inline __attribute__ (( always_inline )) void
|
||||
resolv_unplug ( struct resolv_interface *resolv ) {
|
||||
plug ( &resolv->intf, &null_resolv.intf );
|
||||
intf_plug ( &resolv->intf, &null_resolv.intf );
|
||||
}
|
||||
|
||||
/**
|
||||
|
|
|
@ -238,7 +238,7 @@ xfer_put ( struct xfer_interface *xfer ) {
|
|||
*/
|
||||
static inline __attribute__ (( always_inline )) void
|
||||
xfer_plug ( struct xfer_interface *xfer, struct xfer_interface *dest ) {
|
||||
plug ( &xfer->intf, &dest->intf );
|
||||
intf_plug ( &xfer->intf, &dest->intf );
|
||||
}
|
||||
|
||||
/**
|
||||
|
@ -249,7 +249,7 @@ xfer_plug ( struct xfer_interface *xfer, struct xfer_interface *dest ) {
|
|||
*/
|
||||
static inline __attribute__ (( always_inline )) void
|
||||
xfer_plug_plug ( struct xfer_interface *a, struct xfer_interface *b ) {
|
||||
plug_plug ( &a->intf, &b->intf );
|
||||
intf_plug_plug ( &a->intf, &b->intf );
|
||||
}
|
||||
|
||||
/**
|
||||
|
@ -259,7 +259,7 @@ xfer_plug_plug ( struct xfer_interface *a, struct xfer_interface *b ) {
|
|||
*/
|
||||
static inline __attribute__ (( always_inline )) void
|
||||
xfer_unplug ( struct xfer_interface *xfer ) {
|
||||
plug ( &xfer->intf, &null_xfer.intf );
|
||||
intf_plug ( &xfer->intf, &null_xfer.intf );
|
||||
}
|
||||
|
||||
/**
|
||||
|
|
Reference in New Issue