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  * \see DataBox DataBoxTag tag_name ComputeTag
65  */
66 struct PrefixTag {};
67 
68 /*!
69  * \ingroup DataBoxGroup
70  * \brief Marks a DataBoxTag as being a compute item that executes a function
71  *
72  * \details
73  * Compute items come in two forms: mutating and non-mutating. Mutating
74  * compute items modify a stored value in order to reduce the number of memory
75  * allocations done. For example, if a function would return a `Variables` or
76  * `Tensor<DataVector...>` and is called every time step, then it would be
77  * preferable to use a mutating compute item so that the values in the already
78  * allocated memory can just be changed.
79  * In contrast, non-mutating compute items simply return the new value after a
80  * call (if the value is out-of-date), which is fine for infrequently called
81  * compute items or ones that do not allocate data on the heap.
82  *
83  * A compute item tag contains a member named `function` that is either a
84  * function pointer, or a static constexpr function. The compute item tag
85  * must also have a `label`, same as the DataBox tags, and a type alias
86  * `argument_tags` that is a typelist of the tags that will
87  * be retrieved from the DataBox and whose data will be passed to the function
88  * (pointer). Mutating compute item tags must also contain a type alias named
89  * `return_type` that is the type the function is mutating. The type must be
90  * default constructible.
91  *
92  * \example
93  * Most non-mutating compute item tags will look similar to:
94  * \snippet Test_DataBox.cpp databox_compute_item_tag_example
95  * Note that the arguments can be empty:
96  * \snippet Test_DataBox.cpp compute_item_tag_no_tags
97  *
98  * Mutating compute item tags are of the form:
99  * \snippet Test_DataBox.cpp databox_mutating_compute_item_tag
100  * where the function is:
101  * \snippet Test_DataBox.cpp databox_mutating_compute_item_function
102  *
103  * You can also have `function` be a function instead of a function pointer,
104  * which offers a lot of simplicity for very simple compute items.
105  * \snippet Test_DataBox.cpp compute_item_tag_function
106  *
107  * \see DataBox SimpleTag tag_name PrefixTag
108  */
109 struct ComputeTag {};
110 
111 } // namespace db
db::ComputeTag
Marks a DataBoxTag as being a compute item that executes a function.
Definition: Tag.hpp:109
db::PrefixTag
Marks an item as being a prefix to another tag.
Definition: Tag.hpp:66
db::SimpleTag
Tags for the DataBox inherit from this type.
Definition: Tag.hpp:23
db::BaseTag
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
db
Namespace for DataBox related things.
Definition: DataBox.hpp:42