Tag.hpp
1 // Distributed under the MIT License.
2 // See LICENSE.txt for details.
3 
4 #pragma once
5 
6 namespace db {
7 /*!
8  * \ingroup DataBoxGroup
9  * \brief Tags for the DataBox inherit from this type
10  *
11  * \details
12  * Used to mark a type as being a SimpleTag so that it can be used in a
13  * DataBox.
14  *
15  * \derivedrequires
16  * - type alias `type` of the type this SimpleTag represents
17  *
18  * \example
19  * \snippet Test_DataBox.cpp databox_tag_example
20  *
21  * \see DataBox PrefixTag tag_name
22  */
23 struct SimpleTag {};
24 
25 /*!
26  * \ingroup DataBoxGroup
27  * \brief Tags that are base tags, i.e. a simple or compute tag must derive
28  * off them for them to be useful
29  *
30  * Base tags do not need to contain type information, unlike simple
31  * tags which must contain the type information. Base tags are designed so
32  * that retrieving items from the DataBox or setting argument tags in compute
33  * items can be done without any knowledge of the type of the item.
34  *
35  * To use the base mechanism the base tag must inherit off of
36  * `BaseTag` and NOT `SimpleTag`. This is very important for the
37  * implementation. Inheriting off both and not making the tag either a simple
38  * item or compute item is undefined behavior and is likely to end in extremely
39  * complicated compiler errors.
40  */
41 struct BaseTag {};
42 
43 /*!
44  * \ingroup DataBoxGroup
45  * \brief Marks an item as being a prefix to another tag
46  *
47  * \details
48  * Used to mark a type as being a DataBoxTag where the `label` is a prefix to
49  * the DataBoxTag that is a member type alias `tag`. A prefix tag must contain a
50  * type alias named `type` with the type of the Tag it is a prefix to, as well
51  * as a type alias `tag` that is the type of the Tag that this prefix tag is
52  * a prefix for. A prefix tag must also have a `label` equal to the name of
53  * the struct (tag).
54  *
55  * \derivedrequires
56  * - type alias `tag` of the DataBoxTag that this tag is a prefix to
57  * - type alias `type` that is the type that this PrefixTag holds
58  * - static `std::string name()` method that returns a runtime name for the tag.
59  *
60  * \example
61  * A PrefixTag tag has the structure:
62  * \snippet Test_DataBox.cpp databox_prefix_tag_example
63  *
64  * The name used to retrieve a prefix tag from the DataBox is:
65  * \snippet Test_DataBox.cpp databox_name_prefix
66  *
67  *
68  * \see DataBox DataBoxTag tag_name ComputeTag
69  */
70 struct PrefixTag {};
71 
72 /*!
73  * \ingroup DataBoxGroup
74  * \brief Marks a DataBoxTag as being a compute item that executes a function
75  *
76  * \details
77  * Compute items come in two forms: mutating and non-mutating. Mutating
78  * compute items modify a stored value in order to reduce the number of memory
79  * allocations done. For example, if a function would return a `Variables` or
80  * `Tensor<DataVector...>` and is called every time step, then it would be
81  * preferable to use a mutating compute item so that the values in the already
82  * allocated memory can just be changed.
83  * In contrast, non-mutating compute items simply return the new value after a
84  * call (if the value is out-of-date), which is fine for infrequently called
85  * compute items or ones that do not allocate data on the heap.
86  *
87  * A compute item tag contains a member named `function` that is either a
88  * function pointer, or a static constexpr function. The compute item tag
89  * must also have a `label`, same as the DataBox tags, and a type alias
90  * `argument_tags` that is a typelist of the tags that will
91  * be retrieved from the DataBox and whose data will be passed to the function
92  * (pointer). Mutating compute item tags must also contain a type alias named
93  * `return_type` that is the type the function is mutating. The type must be
94  * default constructible.
95  *
96  * \example
97  * Most non-mutating compute item tags will look similar to:
98  * \snippet Test_DataBox.cpp databox_compute_item_tag_example
99  * Note that the arguments can be empty:
100  * \snippet Test_DataBox.cpp compute_item_tag_no_tags
101  *
102  * Mutating compute item tags are of the form:
103  * \snippet Test_DataBox.cpp databox_mutating_compute_item_tag
104  * where the function is:
105  * \snippet Test_DataBox.cpp databox_mutating_compute_item_function
106  *
107  * You can also have `function` be a function instead of a function pointer,
108  * which offers a lot of simplicity for very simple compute items.
109  * \snippet Test_DataBox.cpp compute_item_tag_function
110  *
111  * \see DataBox SimpleTag tag_name PrefixTag
112  */
113 struct ComputeTag {};
114 
115 } // namespace db
Marks a DataBoxTag as being a compute item that executes a function.
Definition: Tag.hpp:113
Tags for the DataBox inherit from this type.
Definition: Tag.hpp:23
Namespace for DataBox related things.
Definition: DataBox.hpp:42
Marks an item as being a prefix to another tag.
Definition: Tag.hpp:70
Tags that are base tags, i.e. a simple or compute tag must derive off them for them to be useful...
Definition: Tag.hpp:41