ucx: comparison src/cx/iterator.h

-:16e2a3391e88
+:d4baf4dd55c3
 #ifndef UCX_ITERATOR_H
 #define UCX_ITERATOR_H
 #include "common.h"
-/**
+#define CX_ITERATOR_BASE \
-* The base of mutating and non-mutating iterators.
+/** \
-*/
+* True iff the iterator points to valid data. \
-struct cx_iterator_base_s {
+*/ \
-/**
+__attribute__ ((__nonnull__)) \
-* True iff the iterator points to valid data.
+bool (*valid)(void const *); \
-*/
+/** \
-__attribute__ ((__nonnull__))
+* Returns a pointer to the current element. \
-bool (*valid)(void const *);
+* \
+* When valid returns false, the behavior of this function is undefined. \
-/**
+*/ \
-* Returns a pointer to the current element.
+__attribute__ ((__nonnull__)) \
-*
+void *(*current)(void const *); \
-* When valid returns false, the behavior of this function is undefined.
+/** \
-*/
+* Original implementation in case the function needs to be wrapped. \
-__attribute__ ((__nonnull__))
+*/ \
-void *(*current)(void const *);
+__attribute__ ((__nonnull__)) \
+void *(*current_impl)(void const *); \
-/**
+/** \
-* Original implementation in case the function needs to be wrapped.
+* Advances the iterator. \
-*/
+* \
-__attribute__ ((__nonnull__))
+* When valid returns false, the behavior of this function is undefined. \
-void *(*current_impl)(void const *);
+*/ \
+__attribute__ ((__nonnull__)) \
-/**
+void (*next)(void *); \
-* Advances the iterator.
+/** \
-*
+* Indicates whether this iterator may remove elements. \
-* When valid returns false, the behavior of this function is undefined.
+*/ \
-*/
+bool mutating; \
-__attribute__ ((__nonnull__))
+/** \
-void (*next)(void *);
+* Internal flag for removing the current element when advancing. \
+*/ \
-/**
-* Indicates whether this iterator may remove elements.
-*/
-bool mutating;
-/**
-* Internal flag for removing the current element when advancing.
-*/
 bool remove;
-};
+/**
-/**
+* Internal iterator struct - use CxIterator.
-* Internal iterator struct - use CxMutIterator.
+*/
-*/
+struct cx_iterator_s {
-struct cx_mut_iterator_s {
+CX_ITERATOR_BASE
 /**
-* The base properties of this iterator.
+* Handle for the current element.
-*/
-struct cx_iterator_base_s base;
-/**
-* Handle for the current element, if required.
 */
 void *elem_handle;
 /**
 * Handle for the source collection, if any.
 */
-void *src_handle;
+union {
+/**
+* Access for mutating iterators.
+*/
+void *m;
+/**
+* Access for normal iterators.
+*/
+void const *c;
+} src_handle;
 /**
 * Field for storing a key-value pair.
 * May be used by iterators that iterate over k/v-collections.
 */
 */
 size_t elem_count;
 };
 /**
-* Mutating iterator value type.
+* Iterator type.
 *
-* An iterator points to a certain element in an (possibly unbounded) chain of elements.
-* Iterators that are based on collections (which have a defined "first" element), are supposed
-* to be "position-aware", which means that they keep track of the current index within the collection.
-*
-* @note Objects that are pointed to by an iterator are mutable through that iterator. However, if the
-* iterator is based on a collection and the underlying collection is mutated by other means than this iterator
-* (e.g. elements added or removed), the iterator becomes invalid (regardless of what cxIteratorValid() returns)
-* and MUST be re-obtained from the collection.
-*
-* @see CxIterator
-*/
-typedef struct cx_mut_iterator_s CxMutIterator;
-/**
-* Internal iterator struct - use CxIterator.
-*/
-struct cx_iterator_s {
-/**
-* The base properties of this iterator.
-*/
-struct cx_iterator_base_s base;
-/**
-* Handle for the current element, if required.
-*/
-void *elem_handle;
-/**
-* Handle for the source collection, if any.
-*/
-void const *src_handle;
-/**
-* Field for storing a key-value pair.
-* May be used by iterators that iterate over k/v-collections.
-*/
-struct {
-/**
-* A pointer to the key.
-*/
-void const *key;
-/**
-* A pointer to the value.
-*/
-void *value;
-} kv_data;
-/**
-* Field for storing a slot number.
-* May be used by iterators that iterate over multi-bucket collections.
-*/
-size_t slot;
-/**
-* If the iterator is position-aware, contains the index of the element in the underlying collection.
-* Otherwise, this field is usually uninitialized.
-*/
-size_t index;
-/**
-* The size of an individual element.
-*/
-size_t elem_size;
-/**
-* May contain the total number of elements, if known.
-* Shall be set to \c SIZE_MAX when the total number is unknown during iteration.
-*/
-size_t elem_count;
-};
-/**
-* Iterator value type.
 * An iterator points to a certain element in a (possibly unbounded) chain of elements.
 * Iterators that are based on collections (which have a defined "first" element), are supposed
 * to be "position-aware", which means that they keep track of the current index within the collection.
 *
 * @note Objects that are pointed to by an iterator are always mutable through that iterator. However,
-* this iterator cannot mutate the collection itself (add or remove elements) and any mutation of the
+* any concurrent mutation of the collection other than by this iterator makes this iterator invalid
-* collection by other means makes this iterator invalid (regardless of what cxIteratorValid() returns).
+* and it must not be used anymore.
-*
-* @see CxMutIterator
 */
 typedef struct cx_iterator_s CxIterator;
 /**
 * Checks if the iterator points to valid data.
 * This is especially false for past-the-end iterators.
 *
 * @param iter the iterator
 * @return true iff the iterator points to valid data
 */
-#define cxIteratorValid(iter) (iter).base.valid(&(iter))
+#define cxIteratorValid(iter) (iter).valid(&(iter))
 /**
 * Returns a pointer to the current element.
 *
 * The behavior is undefined if this iterator is invalid.
 *
 * @param iter the iterator
 * @return a pointer to the current element
 */
-#define cxIteratorCurrent(iter) (iter).base.current(&iter)
+#define cxIteratorCurrent(iter) (iter).current(&iter)
 /**
 * Advances the iterator to the next element.
 *
 * @param iter the iterator
 */
-#define cxIteratorNext(iter) (iter).base.next(&iter)
+#define cxIteratorNext(iter) (iter).next(&iter)
 /**
 * Flags the current element for removal, if this iterator is mutating.
 *
 * @param iter the iterator
 */
-#define cxIteratorFlagRemoval(iter) (iter).base.remove |= (iter).base.mutating
+#define cxIteratorFlagRemoval(iter) (iter).remove |= (iter).mutating
 /**
 * Loops over an iterator.
 * @param type the type of the elements
 * @param elem the name of the iteration variable
 * @param remove_keeps_order \c true if the order of elements must be preserved
 * when removing an element
 * @return an iterator for the specified array
 */
 __attribute__((__warn_unused_result__))
-CxMutIterator cxMutIterator(
+CxIterator cxMutIterator(
 void *array,
 size_t elem_size,
 size_t elem_count,
 bool remove_keeps_order
 );

Mercurial > hg > ucx / file comparison

comparison: src/cx/iterator.h

src/cx/iterator.h