| # The Builder & Parameter Bundle Patterns | |
| The builder and parameter bundle patterns allow for giving a class a lot of | |
| configuration options at compile time, while leaving the runtime API small and | |
| the runtime constraints clear. | |
| Suppose that you are implementing a new class C, which has a name, a color, a | |
| size, and a URL associated with it, along with a handful of boolean parameters, | |
| each of which default to false. All of these values should be set before the C | |
| is actually used for anything. That class might look like this: | |
| class C { | |
| public: | |
| // Invariant: none of the members can change after you call Init(). | |
| void Init(); | |
| private: | |
| const std::string name_; | |
| const gfx::Color color_; | |
| const gfx::Size size_; | |
| const GURL url_; | |
| const bool is_cool_ = false; | |
| const bool is_nice_ = false; | |
| const bool is_friendly = false; | |
| }; | |
| There are three ways you might choose to make this class configurable: | |
| 1. Have the constructor take initial values for all of these arguments, or even | |
| have several constructors which take different subsets of the arguments. | |
| 2. Have the constructor take no arguments, and instead expose setters for all of | |
| these values, and enforce the invariant of DoStuff() some other way. | |
| 3. Have the constructor take values for all the arguments with no sensible | |
| default, and expose setters for the values that do have sensible defaults. | |
| Most classes end up doing one of these, and have an API that looks roughly like | |
| this: | |
| class C { | |
| public: | |
| C(std::string name, gfx::Color color, gfx::Size size, GURL url); | |
| void Init(); | |
| void set_is_cool(bool is_cool) { is_cool_ = is_cool; } | |
| void set_is_nice(bool is_nice) { is_nice_ = is_nice; } | |
| void set_is_friendly(bool is_friendly) { is_friendly_ = is_friendly; } | |
| private: | |
| ... | |
| // Note that these now have to be non-const, even though they are | |
| // logically const, because the setters are exposed to mutate them before | |
| // use. | |
| bool is_cool_; | |
| bool is_nice_; | |
| bool is_friendly_; | |
| }; | |
| Your class is forced into either: | |
| * Exposing every configuration option as a constructor argument, or | |
| * Allowing some things that are configurable only at construction to be set | |
| any time after construction, with errors caught at runtime | |
| The builder pattern (and the parameter bundle pattern, a simpler relative) offer | |
| a way out of this bind. | |
| ## Parameter Bundles | |
| A parameter bundle is an object that encapsulates all the parameters to another | |
| method, often to a constructor. For example, we might structure our class C like | |
| this: | |
| class C { | |
| public: | |
| struct Params { | |
| std::string name; | |
| // ... | |
| }; | |
| C(Params params); | |
| private: | |
| const std::string name_; | |
| // ... | |
| }; | |
| As long as the params struct is well-structured this may be all you need, and it | |
| can often significantly simplify constructing complicated classes if callers are | |
| allowed to fill in only those parts of the param bundle that they care about. | |
| However, there's a problem: constructors are not allowed to fail in C++. That | |
| implies that it has to be impossible to *make* an invalid `C::Params`, because | |
| if we did pass such an invalid parameter bundle into `C::C()`, the constructor | |
| would have no way to signal failure. We really want to ensure that we can only | |
| get an instance of `C` that is configured in a valid way. | |
| We can do that by adding a factory function to C: | |
| class C { | |
| public: | |
| unique_ptr<C> Make(Params params); | |
| private: | |
| // Since this is private, we can assume Params was validated by the | |
| // factory function first. | |
| C(Params params); | |
| }; | |
| But in the process, we've cluttered the public API of C up with a lot of the | |
| details about how one manufactures an instance of C. What if we could avoid | |
| doing that? Enter... | |
| ## The Builder Pattern | |
| The key idea here is that instead of defining a `C::Params` class, we define a | |
| `C::Builder` class, which knows how to configure and then construct a new | |
| instance of `C`. That might look like this: | |
| class C { | |
| public: | |
| class Builder; // defined elsewhere | |
| private: | |
| friend class Builder; | |
| C(Builder builder); // only called from C::Builder | |
| }; | |
| and now our `Builder` class has an interface like this: | |
| class Builder { | |
| public: | |
| Builder(); | |
| void set_name(std::string name); | |
| void set_color(gfx::Color color): | |
| // ... | |
| std::unique_ptr<C> Build(); | |
| } | |
| To an extent, this is just a syntactic variation of the parameter bundle | |
| pattern, but it does allow for one really nice convenience technique. If, | |
| instead of returning void, we have our setters return a reference to the Builder | |
| object itself: | |
| class Builder { | |
| public: | |
| Builder(); | |
| Builder& set_name(std::string name); | |
| Builder& set_color(gfx::Color color); | |
| // ... | |
| std::unique_ptr<C> Build(); | |
| } | |
| then instead of writing this: | |
| C::Builder builder; | |
| builder.set_name(name); | |
| builder.set_color(color); | |
| auto c = builder.Build(); | |
| we can write this: | |
| auto c = C::Builder().set_name(name) | |
| .set_color(color) | |
| .Build(); | |
| which lets us avoid naming the temporary builder object. | |
| ## Parameter pattern only for optional parameters | |
| It's also possible to use a version of the parameter/builder pattern only for | |
| optional arguments. In this case we make use of `Params&` to be able to chain | |
| calls like `Params().set_foo().set_bar()`, but we may not have a Build() method. | |
| In the first example, this would be: | |
| class C { | |
| public: | |
| class Params { | |
| public: | |
| Params(); | |
| Params& set_is_cool(bool is_cool) { is_cool_ = is_cool; return *this; } | |
| ... | |
| bool is_cool() const { return is_cool_; } | |
| ... | |
| private: | |
| bool is_cool_ = false; | |
| bool is_nice_ = false; | |
| bool is_friendly = false; | |
| }; | |
| // Populates all fields. Optional fields take their values from `params`. | |
| C(std::string name, gfx::Color color, gfx::Size size, GURL url, | |
| Params params = Params()); | |
| private: | |
| const std::string name_; | |
| const gfx::Color color_; | |
| const gfx::Size size_; | |
| const GURL url_; | |
| const bool is_cool_; | |
| const bool is_nice_; | |
| const bool is_friendly; | |
| }; | |
| Doing so lets us construct an object without awareness of the optional `Params` | |
| argument: | |
| C("foo", ...) | |
| While making `C` objects with optional parameters readable and without | |
| temporary variables: | |
| C("foo", ..., Params().set_is_cool(true)); | |
| ## Use This Pattern When | |
| * Your class has more than half a dozen or so configuration options, most of | |
| which should not be changed once the object is "in use" | |
| * Your class has invalid sets of configuration options that should be prohibited | |
| * Your class has complicated configuration options of any sort that want runtime | |
| checking (places you might have previously used the [bool Init() | |
| pattern](bool-init.md)) | |
| ## Alternatives / See Also | |
| * Regular constructor parameters | |
| * Instance variables with public setters | |
| ## Examples in Chromium | |
| * [DialogModel::Builder](https://source.chromium.org/chromium/chromium/src/+/main:ui/base/models/dialog_model.h;drc=72186360334350c90b9b94515b3c82bea25e27ff;l=88) | |
| * [ChildThreadImpl::Builder](https://source.chromium.org/chromium/chromium/src/+/main:content/child/child_thread_impl.h;l=273?q=Builder%20file:%5C.h$%20-file:%5Ethird_party%2F&ss=chromium%2Fchromium%2Fsrc) | |
| * [TestingProfile::Builder](https://source.chromium.org/chromium/chromium/src/+/main:chrome/test/base/testing_profile.h;l=97?q=Builder%20file:%5C.h$%20-file:%5Ethird_party%2F&ss=chromium%2Fchromium%2Fsrc) |