- * and initializes '*statep' with any data needed for iteration. On
- * failure, returns a positive errno value. */
- int (*flow_dump_start)(const struct dpif *dpif, void **statep);
-
- /* Attempts to retrieve another flow from 'dpif' for 'state', which was
- * initialized by a successful call to the 'flow_dump_start' function for
- * 'dpif'. On success, updates the output parameters as described below
- * and returns 0. Returns EOF if the end of the flow table has been
- * reached, or a positive errno value on error. This function will not be
- * called again once it returns nonzero within a given iteration (but the
- * 'flow_dump_done' function will be called afterward).
- *
- * On success, if 'key' and 'key_len' are nonnull then '*key' and
- * '*key_len' must be set to Netlink attributes with types OVS_KEY_ATTR_*
- * representing the dumped flow's key. If 'actions' and 'actions_len' are
- * nonnull then they should be set to Netlink attributes with types
- * OVS_ACTION_ATTR_* representing the dumped flow's actions. If 'stats'
- * is nonnull then it should be set to the dumped flow's statistics.
+ * and initializes '*iterp' with any shared data needed for iteration.
+ * On failure, returns a positive errno value. */
+ int (*flow_dump_start)(const struct dpif *dpif, void **iterp);
+
+ /* Attempts to retrieve another flow from 'dpif' for 'iter', using
+ * 'state' for storage. 'iter' must have been initialized by a successful
+ * call to the 'flow_dump_start' function for 'dpif'. 'state' must have
+ * been initialised with a call to the 'flow_dump_state_init' function for
+ * 'dpif.
+ *
+ * On success, updates the output parameters as described below and returns
+ * 0. Returns EOF if the end of the flow table has been reached, or a
+ * positive errno value on error. Multiple threads may use the same 'dpif'
+ * and 'iter' with this function, but all other parameters must be
+ * different for each thread. If this function returns non-zero,
+ * subsequent calls with the same arguments will also return non-zero.
+ *
+ * On success:
+ *
+ * - If 'key' and 'key_len' are nonnull, then '*key' and '*key_len'
+ * must be set to Netlink attributes with types OVS_KEY_ATTR_*
+ * representing the dumped flow's key.
+ *
+ * - If 'mask' and 'mask_len' are nonnull then '*mask' and '*mask_len'
+ * must be set to Netlink attributes with types of OVS_KEY_ATTR_*
+ * representing the dumped flow's mask.
+ *
+ * - If 'actions' and 'actions_len' are nonnull then they should be set
+ * to Netlink attributes with types OVS_ACTION_ATTR_* representing
+ * the dumped flow's actions.
+ *
+ * - If 'stats' is nonnull then it should be set to the dumped flow's
+ * statistics.