Mercurial > hg > ucx / changeset

     1.1 --- a/docs/src/features.md	Sat Jul 01 14:05:52 2023 +0200
     1.2 +++ b/docs/src/features.md	Sat Jul 01 14:29:16 2023 +0200
     1.3 @@ -186,6 +186,25 @@
     1.4  
     1.5  *Header file:* [collection.h](api/collection_8h.html)
     1.6  
     1.7 +Collections in UCX 3 have several common features.
     1.8 +If you want to implement an own collection data type that uses the same features, you can use the
     1.9 +`CX_COLLECTION_MEMBERS` macro at the beginning of your struct to roll out all members a usual UCX collection has.
    1.10 +```c
    1.11 +struct my_fancy_collection_s {
    1.12 +    CX_COLLECTION_MEMBERS
    1.13 +    struct my_collection_data_s *data;
    1.14 +};
    1.15 +```
    1.16 +Based on this structure, this header provides some convenience macros for invoking the destructor functions
    1.17 +that are part of the basic collection members.
    1.18 +The idea of having destructor functions within a collection is that you can destroy the collection _and_ the
    1.19 +contents with one single function call.
    1.20 +When you are implementing a collection, you are responsible for invoking the destructors at the right places, e.g.
    1.21 +when removing (and deleting) elements in the collection, clearing the collection, or - the most prominent case -
    1.22 +destroying the collection.
    1.23 +
    1.24 +You can always look at the UCX list and map implementations if you need some inspiration.
    1.25 +
    1.26  ## List
    1.27  
    1.28  *Header file:* [list.h](api/list_8h.html)