From e71b83b22b3ce8ddb6b5ba91948c5a1b937ef0fb Mon Sep 17 00:00:00 2001 From: Michael Brown Date: Thu, 12 Jun 2008 19:43:25 +0100 Subject: [PATCH] [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 --- src/core/interface.c | 236 ++++++++++++++++++++++++++++++++--- src/include/ipxe/interface.h | 203 ++++++++++++++++++++++++++---- src/include/ipxe/job.h | 6 +- src/include/ipxe/resolv.h | 6 +- src/include/ipxe/xfer.h | 6 +- 5 files changed, 413 insertions(+), 44 deletions(-) diff --git a/src/core/interface.c b/src/core/interface.c index d1583a8a..f0c0ae64 100644 --- a/src/core/interface.c +++ b/src/core/interface.c @@ -18,19 +18,42 @@ FILE_LICENCE ( GPL2_OR_LATER ); +#include #include /** @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; } diff --git a/src/include/ipxe/interface.h b/src/include/ipxe/interface.h index 41041054..49add330 100644 --- a/src/include/ipxe/interface.h +++ b/src/include/ipxe/interface.h @@ -3,23 +3,116 @@ /** @file * - * Object communication interfaces + * Object interfaces * */ FILE_LICENCE ( GPL2_OR_LATER ); +#include #include -/** 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 */ diff --git a/src/include/ipxe/job.h b/src/include/ipxe/job.h index 893a7901..870b2e83 100644 --- a/src/include/ipxe/job.h +++ b/src/include/ipxe/job.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 ); } /** diff --git a/src/include/ipxe/resolv.h b/src/include/ipxe/resolv.h index c7d61998..767614bd 100644 --- a/src/include/ipxe/resolv.h +++ b/src/include/ipxe/resolv.h @@ -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 ); } /** diff --git a/src/include/ipxe/xfer.h b/src/include/ipxe/xfer.h index ad41e932..8a3f9bb1 100644 --- a/src/include/ipxe/xfer.h +++ b/src/include/ipxe/xfer.h @@ -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 ); } /**