--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/Writerside/topics/iterator.h.md	Thu Jan 23 01:33:36 2025 +0100
@@ -0,0 +1,21 @@
+# iterator.h
+
+In UCX 3 a new feature has been introduced to write own iterators, that work with the `cx_foreach` macro.
+In previous UCX releases there were different hard-coded foreach macros for lists and maps that were not customizable.
+Now, creating an iterator is as simple as creating a `CxIterator` struct and setting the fields in a meaningful way.
+
+You do not always need all fields in the iterator structure, depending on your use case.
+Sometimes you only need the `index` (for example when iterating over simple lists), and other times you will need the
+`slot` and `kv_data` fields (for example when iterating over maps).
+
+If the predefined fields are insufficient for your use case, you can alternatively create your own iterator structure
+and place the `CX_ITERATOR_BASE` macro as first member of that structure.
+
+Usually an iterator is not mutating the collection it is iterating over.
+In some programming languages it is even disallowed to change the collection while iterating with foreach.
+But sometimes it is desirable to remove an element from the collection while iterating over it.
+For this purpose, most collections allow the creation of a _mutating_ iterator.
+The only differences are, that the `mutating` flag is `true` and the `src_handle` is not const.
+On mutating iterators it is allowed to call the `cxFlagForRemoval()` function, which instructs the iterator to remove
+the current element from the collection on the next call to `cxIteratorNext()` and clear the flag afterward.
+If you are implementing your own iterator, it is up to you to implement this behavior.