esp::core::Configuration changed to use unordered_map of variant-like instead of Magnum::ConfigurationGroups by jturner65 · Pull Request #1433 · facebookresearch/habitat-sim

jturner65 · 2021-08-11T18:59:19Z

Motivation and Context

Currently Habitat-sim uses Magnum::ConfigurationGroups as the backing datastructure for all metadata loaded via JSON configuration files. A ConfigurationGroup saves all data as strings, and the original type of that data is lost once it is loaded into the system. This is particularly problematic with the user-defined attributes that habitat now supports. Upon read, the type of the user-defined value is inferred by the format of the data in the source JSON. With the upcoming functionality to save JSON configs to disk, including user_defined values, without having the type known will cause all data to be saved to disk as strings.

This PR replaces the ConfigurationGroup as the container for esp::core::Configuration and instead uses a ( collection of typed std::unordered_maps. ) single unordered map of ConfigValues, which use a tagged union/variant structure to retain type information and safety.

One question to consider : do we wish to remove the ConfigurationGroup as the backing structure for esp::core::Configuration. A different structure can be easily designed to replace esp::core::Configuration as the base class for the various configuration attributes that Habitat uses.

If nobody is using an esp::core::Configuration currently outside of the Metadata attributes/configuration subsystem, then the changes proposed by this PR can probably proceed with impunity; if, however, the ConfigurationGroup functionality backing habitat's Configuration is desired to remain, then I should instead create another class to back the attributes.

How Has This Been Tested

Locally, all c++ and python tests pass.

Types of changes

Docs change / refactoring / dependency upgrade
Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist

My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have read the CONTRIBUTING document.
I have completed my CLA (see CONTRIBUTING)
I have added tests to cover my changes.
All new and existing tests passed.

Skylion007 · 2021-08-11T20:23:11Z

Really would like to hear @mosra's input on this. Might be a better solution.

jturner65 · 2021-08-16T21:11:56Z

Discussing this refactor with @mosra, he suggested I investigate a tagged union storage container, so this push introduces this. Now all variables are stored in a single map, regardless of type, and accessed appropriately based on the "tag"-specified type they are. A std::variant/std::visitor system would have been safer and more streamlined, but these require c++17, which we do not currently support.

eundersander

Overall seems good. It is quite verbose, e.g. lots of switch statements... hopefully we aren't adding new types often.

I spotted a number of changes that seemed to be unrelated to the config stuff. Let's move them to separate PRs so they get properly reviewed.

Side note: we should move to C++17 soon! I guess a lot of this is re-inventing std::any/std::variant.

src/esp/core/Configuration.cpp

src/esp/metadata/attributes/SceneAttributes.h

src/esp/physics/PhysicsObjectBase.h

tests/test_configs.py

src/esp/metadata/attributes/PhysicsManagerAttributes.cpp

src/esp/core/Configuration.h

aclegg3

I'd also like Mosra's opinion before merge. Overall, I like this approach.

I chatted with @jturner65 and came up with a couple of other nice-to-have features:

a query for all keys as a map/dict (key -> type enum) and supporting type enum bindings.
a get(key, type) python function for easy access out of the dict returned by (1.)
sub configuration accessor bindings: get a sub configuration as a separate Configuration object (nested hierarchal structure) with option to get copy or ref and to register modified copies back into a subconfiguration
query list of sub configuration keys

src/esp/core/Configuration.cpp

Skylion007 · 2021-08-18T16:29:35Z

src/esp/core/Configuration.cpp

+      return std::to_string(d);
+    case ConfigStoredType::String:
+      return s;
+    case ConfigStoredType::MagnumVec3: {


Doesn't Magnum have some sort of serializer for these types @mosra?

It has, one for debug output (where the goal is human readability) and one for (INI-style, space-delimited) configuration values. Neither of those produces what's supposedly needed here, tho (JSON-like formatting).

mosra

Went through the python bindings and the "other code" first, will focus on the internals in a separate review.

mosra · 2021-08-19T13:41:24Z

src/esp/bindings/AttributesBindings.cpp

+              const Magnum::Quaternion& val) {
+             const auto ptr = self.editUserConfiguration();
+             return ptr->set(key, val);
+           })


I think those could all be just set_user_config overloads without the type name, no? Or, even more pythonic, implement either a __setitem__ operator or __setattr__, so instead of

foo.set_user_config("bar", bar)

you'd do

foo.user_config['bar'] = bar

or

foo.user_config.bar = bar

The last one might be a bit controversial, argparse uses it for example but it might be confusing to some. Ask the others for opinion first :)

src/esp/bindings/AttributesBindings.cpp

mosra · 2021-08-19T13:54:27Z

src/esp/bindings/CoreBindings.cpp

+  py::enum_<ConfigStoredType>(m, "ConfigStoredType")
+      .value("Unknown", ConfigStoredType::Unknown)
+      .value("Boolean", ConfigStoredType::Boolean)
+      .value("Integer", ConfigStoredType::Integer)
+      .value("Double", ConfigStoredType::Double)
+      .value("String", ConfigStoredType::String)
+      .value("MagnumVec3", ConfigStoredType::MagnumVec3)
+      .value("MagnumQuat", ConfigStoredType::MagnumQuat)
+      .value("MagnumRad", ConfigStoredType::MagnumRad);


This suggestion is out of my league and I don't know how to express it via pybind (maybe @Skylion007 could help?) but what about get_type() returning a Python type object? So you'd have e.g.

foo.set_string('bar', 'a string') assert foo.get_type('bar') == str

Same comment about API naming here as well, could be just foo.bar = 'a string'. And because I think some minor overhead doesn't matter that much, getting the type could be as simple as this, instead of foo.get_type('bar') -- because with the interface designed like this, I think the need for querying just a type and not the value is very minimal:

type(foo.bar)

py::type::of is what you are looking for: pybind/pybind11#2364

I do need to have an equivalent to 'ConfigStoredType::unknown' to handle the edge case where the value has not been properly initialized. Is there a python type equivalent i could use?

py::none would be the thing, I'd say? Similar semantics to a null pointer.

src/esp/bindings/CoreBindings.cpp

mosra · 2021-08-19T14:05:21Z

src/esp/bindings/CoreBindings.cpp

+      .def(
+          "has_rad",
+          [](Configuration& self, const std::string& key) {
+            return self.checkMapForKeyAndType(key, ConfigStoredType::MagnumRad);
+          },
+          R"(Returns true if specified key references a Magnum::Rad value in this configuration.)")


Not sure about usefulness of the has_* APIs, now that you have everything stored in a single map there isn't a possibility of the same key being used for two different types and so this could be expressed simply as this and there's no need to have a dedicated overload for each and every type.

foo.get_type('bar') == mn.Rad

(assuming the above suggestion with get_type() returning a Python type object, which makes it a lot shorter than ConfigStoredType.MagnumRad)

src/esp/metadata/attributes/ObjectAttributes.h

src/esp/metadata/attributes/PhysicsManagerAttributes.h

src/esp/metadata/attributes/SceneAttributes.cpp

src/esp/physics/PhysicsObjectBase.h

src/tests/AttributesManagersTest.cpp

jturner65

I'm going to strip out all the string concatenation changes and put them in another PR. (The only modifications will be what are required to support the underlying changes in the Configuration).

mosra

Another batch, about the internals, I still need to look deeper into the breadcrumb parts.

Sorry in advance for all the comments! :)

src/esp/core/Configuration.h

src/esp/metadata/attributes/AttributesBase.h

src/esp/core/Configuration.h

src/esp/core/Configuration.cpp

src/esp/core/Configuration.h

src/esp/metadata/attributes/LightLayoutAttributes.h

Skylion007 · 2021-08-21T16:05:44Z

A std::variant/std::visitor system would have been safer and more streamlined, but these require c++17, which we do not currently support.
This would be nice to have and PyBind11 has native support for std::variant. Everything seems to compile just fine under C++17 so I would in favor of upgrading as well. https://pybind11.readthedocs.io/en/stable/advanced/cast/stl.html#c-17-library-containers. There are also some minor improvements in PyBind11 you get when using C++17 thanks to fold expressions and better constexpr support.

jturner65 · 2021-08-22T00:04:20Z

A std::variant/std::visitor system would have been safer and more streamlined, but these require c++17, which we do not currently support.

This would be nice to have and PyBind11 has native support for std::variant. Everything seems to compile just fine under C++17 so I would in favor of upgrading as well. https://pybind11.readthedocs.io/en/stable/advanced/cast/stl.html#c-17-library-containers. There are also some minor improvements in PyBind11 you get when using C++17 thanks to fold expressions and better constexpr support.

Just FYI, when I said safer and more streamlined, I meant as compared to the former tagged-union refactor that this PR originally introduced. The system that I replaced it with (with substantial guidance from @mosra ) does not have the same safety concerns.

mosra · 2021-08-22T10:21:47Z

Re std::variant, to clarify my view and repeat to what I said to John privately -- I think what we created here does everything we need, is safe, memory- and runtime-efficient, compiles fast and is reasonably easy to maintain / extend for new types.

On the other hand, std::variant<bool, int, double, Vector3, Quaternion, Rad, std::string, Configuration, ...> would have notorious issues with compile times, where the compile-time cost of accessing a value scales linearly with the number of types a variant can store, and it can quickly become unbearable to the point where people have to "optimize" by storing e.g. a float as a Vector3 to reduce the amount of types used. (Not to mention the "fun" one has to go through with std::visit().) Yes, I'm skeptical about C++17 features.

About python bindings, I think we're fine here, exposing all types in a Pythonic way wasn't too complicated.

aclegg3

Looks good. Once the last couple review changes are addressed I think we can ship this.

mosra

Some more bits to add to #1452, it was easier to add the review here because this PR has the full code.

src/esp/bindings/ConfigBindings.cpp

mosra · 2021-08-26T15:20:36Z

src/esp/bindings/ConfigBindings.cpp

+          R"(Retrieves a string representation of the value referred to by the passed key.)")
+
+      .def("get_bool_keys",
+           &Configuration::getStoredKeys<ConfigStoredType::Boolean>)


Last thing, I don't feel getStoredKeys() needs to be templated, instead it could take the type as a parameter (getKeysByType() and since you have the ConfigStoredType exposed anyway, all these overloads could be just one get_keys_by_type() with the ConfigStoredType as a parameter.

mosra · 2021-08-26T15:21:46Z

src/esp/bindings/ConfigBindings.cpp

+          "key"_a)
+
+      .def(
+          "has_bool",


Same here, there could be a single hasKeyOfType() / has_key_of_type(), taking a ConfigStoredType.

bigbike · 2021-08-27T18:59:20Z

src/esp/core/Configuration.cpp

+      return std::to_string(r.operator float());
+    }
+    default:
+      ESP_CHECK(true, "Unknown/unsupported Type in ConfigValue::getAsString.");


This check is always true, and the error message will never ever be displayed.
Is it a bug here?

consider using:

CORRADE_INTERNAL_ASSERT_UNREACHABLE(); return ""; // dummy to avoid compile warning

There are a couple of similar places like this.

These checks are reachable only if a new type was added to the ConfigStoredType enumeration but not supported by case entries. The ESP_CHECKs were added to provide feedback to illuminate this condition so that it may be remedied, should other safeguards against this situation fail.

Right, missed that, should have been false. @jturner65 can you fix these? Basically all occurences of ESP_CHECK(true, ... are wrong. And since it's unlikely to be hit from user code, even less Python code, it doesn't need to be an ESP_CHECK() either. This is what you're looking for:

CORRADE_ASSERT_UNREACHABLE("Unknown/unsupported Type in ConfigValue::getAsString");

(btw., @bigbike, the return isn't needed, the macro contains a compiler-specific "unreachable code" annotation which does the right thing with no warnins)

Great! thanks for finding this @bigbike and @mosra

bigbike · 2021-08-27T20:44:27Z

src/esp/core/Configuration.cpp

+    case ConfigStoredType::MagnumRad:
+      return cfg.setValue(key, get<Mn::Rad>());
+    default:
+      ESP_CHECK(


here is another place that needs to be fixed.

jturner65 requested review from Skylion007, aclegg3 and mosra August 11, 2021 18:59

facebook-github-bot added the CLA Signed Do not delete this pull request or issue due to inactivity. label Aug 11, 2021

jturner65 force-pushed the Config_UseMaps branch from 258f837 to 52ed767 Compare August 11, 2021 19:29

jturner65 force-pushed the Config_UseMaps branch 4 times, most recently from 484205c to 144b87d Compare August 16, 2021 13:16

jturner65 force-pushed the Config_UseMaps branch 2 times, most recently from 41ba02c to 813ccca Compare August 17, 2021 01:24

jturner65 requested a review from eundersander August 17, 2021 16:28

jturner65 changed the title ~~esp::core::Configuration changed to use unordered_maps instead of Magnum::ConfigurationGroups~~ esp::core::Configuration changed to use unordered_map of tagged union instead of Magnum::ConfigurationGroups Aug 17, 2021

eundersander reviewed Aug 17, 2021

View reviewed changes

aclegg3 reviewed Aug 17, 2021

View reviewed changes

jturner65 force-pushed the Config_UseMaps branch from 229317a to c028559 Compare August 17, 2021 20:26

Skylion007 reviewed Aug 18, 2021

View reviewed changes

src/esp/core/Configuration.cpp Outdated Show resolved Hide resolved

Skylion007 reviewed Aug 18, 2021

View reviewed changes

mosra reviewed Aug 19, 2021

View reviewed changes

jturner65 commented Aug 19, 2021

View reviewed changes

mosra reviewed Aug 19, 2021

View reviewed changes

Skylion007 reviewed Aug 19, 2021

View reviewed changes

src/esp/metadata/attributes/LightLayoutAttributes.h Outdated Show resolved Hide resolved

jturner65 force-pushed the Config_UseMaps branch 2 times, most recently from 6702022 to 9d11bef Compare August 22, 2021 17:09

--more appropriately name json subgroup loading

33939b0

jturner65 added 19 commits August 24, 2021 18:11

--clang-tidy

d806839

--Add config namespace; redesign ConfigValue

b39c920

--further progress on redesign

3a2f83d

--merge miss

379b5c8

--reviewer suggestion.

7a6ff8d

--clang-tidy

e915504

--fix debug stream; clang-tidy

41a993e

--more clang-tidy

c0beac4

--bypass clang-tidy buggy checks - can't be const.

8057fa0

--more specific nolint

985207e

--separate config namespace bindings from other core bindings

d13a2dc

--another erroneous clan-tidy const complaint

f16d626

--fix bug with copy/move; better func names; comments

c7d31c5

--support enum-to-descriptive name lookup for ConfigStoredTypes

8d199c5

--replace type-named getters with template.

b03d0d0

--add hash for ConfigStoredType

2738b4f

--reviewer suggestion

d7d449d

--remove superfluous/confusing template-to-user_config accessors

b53ab13

--attempt to avoid type-punning warning.

8ba4ed8

jturner65 force-pushed the Config_UseMaps branch from 6025609 to 8ba4ed8 Compare August 24, 2021 22:11

aclegg3 approved these changes Aug 24, 2021

View reviewed changes

jturner65 added 2 commits August 25, 2021 08:26

--minor binding fixes

297579b

--more efficient subgroup add

701f9e9

jturner65 merged commit be9bc69 into facebookresearch:master Aug 25, 2021

jturner65 deleted the Config_UseMaps branch August 25, 2021 13:34

jturner65 changed the title ~~esp::core::Configuration changed to use unordered_map of tagged union instead of Magnum::ConfigurationGroups~~ esp::core::Configuration changed to use unordered_map of variant-like instead of Magnum::ConfigurationGroups Aug 25, 2021

jturner65 mentioned this pull request Aug 26, 2021

Configuration performance improvements and functionality enhancemens. #1452

Merged

11 tasks

mosra reviewed Aug 26, 2021

View reviewed changes

bigbike reviewed Aug 27, 2021

View reviewed changes

Conversation

jturner65 commented Aug 11, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested

Types of changes

Checklist

Uh oh!

Skylion007 commented Aug 11, 2021

Uh oh!

jturner65 commented Aug 16, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eundersander left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aclegg3 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mosra left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jturner65 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mosra left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Skylion007 commented Aug 21, 2021

Uh oh!

jturner65 commented Aug 22, 2021

Uh oh!

mosra commented Aug 22, 2021

Uh oh!

aclegg3 left a comment

Choose a reason for hiding this comment

Uh oh!

jturner65 commented Aug 11, 2021 •

edited

Loading

jturner65 commented Aug 16, 2021 •

edited

Loading

jturner65 left a comment •

edited

Loading