Daniel Carvalho has uploaded this change for review. (
https://gem5-review.googlesource.com/c/public/gem5/+/38735 )
Change subject: base: Add documentation to flags.hh
......................................................................
base: Add documentation to flags.hh
Add documentation to the Flags class. Use this opportunity
to rename some arguments to make their intention clearer.
Finally, the constructors have been merged using a default
value of 0.
Change-Id: I924b1d5c20a3e2066be64ab124ae1a5d96d4b3bf
Signed-off-by: Daniel R. Carvalho <oda...@yahoo.com.br>
---
M src/base/flags.hh
1 file changed, 91 insertions(+), 15 deletions(-)
diff --git a/src/base/flags.hh b/src/base/flags.hh
index 8cefd2d..170abc5 100644
--- a/src/base/flags.hh
+++ b/src/base/flags.hh
@@ -1,4 +1,5 @@
/*
+ * Copyright (c) 2020 Daniel R. Carvalho
* Copyright (c) 2008 The Hewlett-Packard Development Company
* All rights reserved.
*
@@ -31,12 +32,18 @@
#include <type_traits>
+/**
+ * Wrapper that groups a few flag bits under the same undelying container.
+ *
+ * @tparam T The type of the underlying container. Must be an unsigned
integer.
+ */
template <typename T>
class Flags
{
private:
static_assert(std::is_unsigned<T>::value, "Flag type must be
unsigned");
+ /** The undelying container of the flags' bits. */
T _flags;
public:
@@ -46,18 +53,17 @@
* @ingroup api_flags
* @{
*/
- Flags() : _flags(0) {}
- Flags(Type flags) : _flags(flags) {}
- /** @} */ // end of api_flags
/**
- * @ingroup api_flags
+ * Initialize flags with a given value. If no value is provided, the
+ * flag bits are initialized cleared.
+ *
+ * @param flags The value to initialize the flags with.
*/
+ Flags(Type flags=0) : _flags(flags) {}
+
operator const Type() const { return _flags; }
- /**
- * @ingroup api_flags
- */
const Flags<T> &
operator=(T flags)
{
@@ -66,19 +72,89 @@
}
/**
- * @ingroup api_flags
- * @{
+ * Verifies whether any bit in the flags is set.
+ *
+ * @return True if any flag bit is set; false otherwise.
*/
bool isSet() const { return _flags; }
- bool isSet(Type flags) const { return (_flags & flags); }
+
+ /**
+ * Verifies whether any bit matching the given mask is set.
+ *
+ * @param mask The mask containing the bits to verify.
+ * @return True if any matching bit is set; false otherwise.
+ */
+ bool isSet(Type mask) const { return (_flags & mask); }
+
+ /**
+ * Verifies whether all bits in the flags are set.
+ *
+ * @return True if all flag bits are set; false otherwise.
+ */
bool allSet() const { return !(~_flags); }
- bool allSet(Type flags) const { return (_flags & flags) == flags; }
+
+ /**
+ * Verifies whether no bits matching the given mask are set.
+ *
+ * @param mask The mask containing the bits to verify.
+ * @return True if matching bits are set; false otherwise.
+ */
+ bool allSet(Type mask) const { return (_flags & mask) == mask; }
+
+ /**
+ * Verifies whether no bits in the flags are set.
+ *
+ * @return True if all flag bits are cleared; false otherwise.
+ */
bool noneSet() const { return _flags == 0; }
- bool noneSet(Type flags) const { return (_flags & flags) == 0; }
+
+ /**
+ * Verifies whether no bits matching the given mask are set.
+ *
+ * @param mask The mask containing the bits to verify.
+ * @return True if matching bits are cleared; false otherwise.
+ */
+ bool noneSet(Type mask) const { return (_flags & mask) == 0; }
+
+ /** Clear all flag's bits. */
void clear() { _flags = 0; }
- void clear(Type flags) { _flags &= ~flags; }
- void set(Type flags) { _flags |= flags; }
- void set(Type f, bool val) { _flags = (_flags & ~f) | (val ? f : 0); }
+
+ /**
+ * Clear all flag's bits matching the given mask.
+ *
+ * @param mask The mask containing the bits to be cleared.
+ */
+ void clear(Type mask) { _flags &= ~mask; }
+
+ /**
+ * Set all flag's bits matching the given mask.
+ *
+ * @param mask The mask containing the bits to be set.
+ */
+ void set(Type mask) { _flags |= mask; }
+
+ /**
+ * Conditionally set or clear some bits of the flag, given a mask.
+ *
+ * @param mask The mask containing the bits to be modified.
+ * @param condition If true, set masked bits; otherwise, clear them.
+ */
+ void
+ set(Type mask, bool condition)
+ {
+ condition ? set(mask) : clear(mask);
+ }
+
+ /**
+ * Replace the contents of the bits matching the mask with the
+ * corresponding bits in the provided flags.
+ *
+ * This is equivalent to:
+ * flags.clear(mask); flags.set(flags & mask);
+ *
+ * @param flags Flags to extract new bits from.
+ * @param mask Mask used to determine which bits are replaced.
+ */
void
update(Type flags, Type mask)
{
--
To view, visit https://gem5-review.googlesource.com/c/public/gem5/+/38735
To unsubscribe, or for help writing mail filters, visit
https://gem5-review.googlesource.com/settings
Gerrit-Project: public/gem5
Gerrit-Branch: develop
Gerrit-Change-Id: I924b1d5c20a3e2066be64ab124ae1a5d96d4b3bf
Gerrit-Change-Number: 38735
Gerrit-PatchSet: 1
Gerrit-Owner: Daniel Carvalho <oda...@yahoo.com.br>
Gerrit-MessageType: newchange
_______________________________________________
gem5-dev mailing list -- gem5-dev@gem5.org
To unsubscribe send an email to gem5-dev-le...@gem5.org
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s
