[ovs-dev] [PATCH] ofproto: Improve description of port dump functions.

[Ben Pfaff]

Thanks, I'll push it.

On Tue, Jun 14, 2011 at 03:33:54PM -0700, Ethan Jackson wrote:
> Looks good to me.
> 
> Ethan
> 
> On Mon, Jun 13, 2011 at 13:21, Ben Pfaff <blp at nicira.com> wrote:
> > Suggested-by: Hao Zheng <hzheng at nicira.com>
> > ---
> > ?ofproto/private.h | ? 79 +++++++++++++++++++++++++++++++++++++++++------------
> > ?1 files changed, 61 insertions(+), 18 deletions(-)
> >
> > diff --git a/ofproto/private.h b/ofproto/private.h
> > index 80c59e4..06e8223 100644
> > --- a/ofproto/private.h
> > +++ b/ofproto/private.h
> > @@ -427,27 +427,70 @@ struct ofproto_class {
> > ? ? ?* convenient. */
> > ? ? int (*port_del)(struct ofproto *ofproto, uint16_t ofp_port);
> >
> > - ? ?/* Attempts to begin dumping the ports in 'ofproto'. ?On success, returns 0
> > - ? ? * and initializes '*statep' with any data needed for iteration. ?On
> > - ? ? * failure, returns a positive errno value. */
> > + ? ?/* Port iteration functions.
> > + ? ? *
> > + ? ? * The client might not be entirely in control of the ports within an
> > + ? ? * ofproto. ?Some hardware implementations, for example, might have a fixed
> > + ? ? * set of ports in a datapath, and the Linux datapath allows the system
> > + ? ? * administrator to externally add and remove ports with ovs-dpctl. ?For
> > + ? ? * this reason, the client needs a way to iterate through all the ports
> > + ? ? * that are actually in a datapath. ?These functions provide that
> > + ? ? * functionality.
> > + ? ? *
> > + ? ? * The 'state' pointer provides the implementation a place to
> > + ? ? * keep track of its position. ?Its format is opaque to the caller.
> > + ? ? *
> > + ? ? * The ofproto provider retains ownership of the data that it stores into
> > + ? ? * ->port_dump_next()'s 'port' argument. ?The data must remain valid until
> > + ? ? * at least the next call to ->port_dump_next() or ->port_dump_done() for
> > + ? ? * 'state'. ?The caller will not modify or free it.
> > + ? ? *
> > + ? ? * Details
> > + ? ? * =======
> > + ? ? *
> > + ? ? * ->port_dump_start() attempts to begin dumping the ports in 'ofproto'.
> > + ? ? * On success, it should return 0 and initialize '*statep' with any data
> > + ? ? * needed for iteration. ?On failure, returns a positive errno value, and
> > + ? ? * the client will not call ->port_dump_next() or ->port_dump_done().
> > + ? ? *
> > + ? ? * ->port_dump_next() attempts to retrieve another port from 'ofproto' for
> > + ? ? * 'state'. ?If there is another port, it should store the port's
> > + ? ? * information into 'port' and return 0. ?It should return EOF if all ports
> > + ? ? * have already been iterated. ?Otherwise, on error, it should return a
> > + ? ? * positive errno value. ?This function will not be called again once it
> > + ? ? * returns nonzero once for a given iteration (but the 'port_dump_done'
> > + ? ? * function will be called afterward).
> > + ? ? *
> > + ? ? * ->port_dump_done() allows the implementation to release resources used
> > + ? ? * for iteration. ?The caller might decide to stop iteration in the middle
> > + ? ? * by calling this function before ->port_dump_next() returns nonzero.
> > + ? ? *
> > + ? ? * Usage Example
> > + ? ? * =============
> > + ? ? *
> > + ? ? * int error;
> > + ? ? * void *state;
> > + ? ? *
> > + ? ? * error = ofproto->ofproto_class->port_dump_start(ofproto, &state);
> > + ? ? * if (!error) {
> > + ? ? * ? ? for (;;) {
> > + ? ? * ? ? ? ? struct ofproto_port port;
> > + ? ? *
> > + ? ? * ? ? ? ? error = ofproto->ofproto_class->port_dump_next(
> > + ? ? * ? ? ? ? ? ? ? ? ? ? ofproto, state, &port);
> > + ? ? * ? ? ? ? if (error) {
> > + ? ? * ? ? ? ? ? ? break;
> > + ? ? * ? ? ? ? }
> > + ? ? * ? ? ? ? // Do something with 'port' here (without modifying or freeing
> > + ? ? * ? ? ? ? // any of its data).
> > + ? ? * ? ? }
> > + ? ? * ? ? ofproto->ofproto_class->port_dump_done(ofproto, state);
> > + ? ? * }
> > + ? ? * // 'error' is now EOF (success) or a positive errno value (failure).
> > + ? ? */
> > ? ? int (*port_dump_start)(const struct ofproto *ofproto, void **statep);
> > -
> > - ? ?/* Attempts to retrieve another port from 'ofproto' for 'state', which was
> > - ? ? * initialized by a successful call to the 'port_dump_start' function for
> > - ? ? * 'ofproto'. ?On success, stores a new ofproto_port into 'port' and
> > - ? ? * returns 0. ?Returns EOF if the end of the port table has been reached,
> > - ? ? * or a positive errno value on error. ?This function will not be called
> > - ? ? * again once it returns nonzero once for a given iteration (but the
> > - ? ? * 'port_dump_done' function will be called afterward).
> > - ? ? *
> > - ? ? * The ofproto provider retains ownership of the data stored in 'port'. ?It
> > - ? ? * must remain valid until at least the next call to 'port_dump_next' or
> > - ? ? * 'port_dump_done' for 'state'. */
> > ? ? int (*port_dump_next)(const struct ofproto *ofproto, void *state,
> > ? ? ? ? ? ? ? ? ? ? ? ? ? struct ofproto_port *port);
> > -
> > - ? ?/* Releases resources from 'ofproto' for 'state', which was initialized by
> > - ? ? * a successful call to the 'port_dump_start' function for 'ofproto'. ?*/
> > ? ? int (*port_dump_done)(const struct ofproto *ofproto, void *state);
> >
> > ? ? /* Polls for changes in the set of ports in 'ofproto'. ?If the set of ports
> > --
> > 1.7.4.4
> >
> > _______________________________________________
> > dev mailing list
> > dev at openvswitch.org
> > http://openvswitch.org/mailman/listinfo/dev
> >