1libfit
2
3Source: https://fuchsia.googlesource.com/fuchsia/+/main/sdk/lib/fit/
4Version: 36303cd2d1611cb1b670235692d01a92e83ecd21
5License:
6
7Copyright 2019 The Fuchsia Authors.
8
9Redistribution and use in source and binary forms, with or without
10modification, are permitted provided that the following conditions are
11met:
12
13   * Redistributions of source code must retain the above copyright
14notice, this list of conditions and the following disclaimer.
15   * Redistributions in binary form must reproduce the above
16copyright notice, this list of conditions and the following disclaimer
17in the documentation and/or other materials provided with the
18distribution.
19
20THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31
32======
33
34FIT is a lean library of portable C++ abstractions for control flow and
35memory management beyond what is offered by the C++ 17 standard library.
36
37FIT only depends on the C++ language and standard library, including some C++17
38library features.  It offers essential enhancements to the C++ standard library
39rather than attempting to replace it or become a framework for writing
40applications.  FIT can be thought of as an "annex" that expresses a few ideas
41we wish the C++ standard library might itself implement someday.
42
43FIT is lean.
44
45## What Belongs in FIT
46
47Several Fuchsia SDK libraries, such as *libfidl*, depend on FIT and on the C++
48standard library.  As these libraries are broadly used, we must take care in
49deciding what features to include in FIT to avoid burdening developers with
50unnecessary code or dependencies.
51
52In general, the goal is to identify specific abstractions that make sense to
53generalize across the entire ecosystem of Fuchsia C++ applications.  These will
54necessarily be somewhat low-level but high impact.  We don't want to add code to
55FIT simply because we think it's cool.  We need evidence that it is a common
56idiom and that a broad audience of developers will significantly benefit from
57its promotion.
58
59Here are a few criteria to consider:
60
61- Is the feature lightweight, general-purpose, and platform-independent?
62- Is the feature not well served by other means, particularly by the C++
63  standard library?
64- Is the feature needed by a Fuchsia SDK library?
65- Does the feature embody a beneficial idiom that clients of the Fuchsia SDK
66  commonly use?
67- Has the feature been re-implemented many times already leading to code
68  fragmentation that we would like to eliminate?
69
70If in doubt, leave it out.  See [Justifications] below.
71
72## What Doesn't Belong in FIT
73
74FIT is not intended to become a catch-all class library.
75
76Specifically prohibited features:
77
78- Features that introduce dependencies on libraries other than the C and C++
79  standard library.
80- Features that only work on certain operating systems.
81- Collection classes where the C++ 17 standard library already offers an
82  adequate (if not perfect) alternative.
83- Classes that impose an implementation burden on clients such as event loops,
84  dispatchers, frameworks, and other glue code.
85
86## Implementation Considerations
87
88FIT is not exception safe (but could be made to be in the future).
89
90## Style Conventions
91
92The API style was modified to fit current android::base library conventions.
93
94In brief:
95
96- Class identifiers are CamelCase
97- Class methods and variable identifiers use "camelCase", class fields use
98  "mCamelCase".
99- Template parameters are `CamelCase`.
100- Preprocessor macros are `UPPER_SNAKE_CASE`.
101
102## Justifications
103
104These sections explain why certain features are in FIT.
105
106### fit::Function
107
108- *libfidl*'s API needs a callable function wrapper with move semantics but
109  C++ 14's `std::function` only supports copyable function objects which forces
110  FIDL to allocate callback state on the heap making programs less efficient
111  and harder to write.
112- Lots of other C++ code uses callbacks extensively and would benefit from move
113  semantics for similar reasons.
114- So we should create a move-only function wrapper to use everywhere.
115
116### fit::Defer
117
118- When writing asynchronous event-driven programs, it can become challenging
119  to ensure that resources remain in scope for the duration of an operation
120  in progress and are subsequently released.
121- The C++ 14 standard library offers several classes with RAII semantics, such
122  as `std::unique_ptr`, which are helpful in these situations.  Unfortunately the
123  C++ 14 standard library does not offer affordances for easily invoking a
124  function when a block or object goes out of scope short of implementing a
125  new class from scratch.
126- We have observed several re-implementations of the same idea throughout the
127  system.
128- So we should create a simple way to invoke a function on scope exit.
129
130### fit::Nullable
131
132- Case study: fit::defer has a need to store a closure that may be nullable.
133  We were able to replace its hand-rolled lifetime management code with
134  fit::nullable thereby vastly simplifying its implementation.
135- Case study: fit::future has a need to track its own validity along with
136  a continuation that may or not be present.
137- Case study: We have previously observed bugs where developers were
138  surprised when assigning a null closure to wrappers such as fit::function
139  fit::defer, or fit::future left these objects in a supposedly "valid"
140  but uninvocable state.  These objects therefore take care to detect
141  null closures and enter an "invalid" state.  Using fit::is_null and
142  fit::nullable makes it easier to eliminate this redundant state and
143  simplifies the API for clients of these wrappers.
144- std::optional can be effective here but it doesn't directly handle nullity
145  so it takes more care to coalesce the null and "not present" states.
146  std::optional also increases the size of the object to carry an extra
147  bool and passing, whereas fit::nullable eliminates this overhead by
148  taking advantage of the underlying value's null state (if there is one).
149- So we introduce fit::nullable to handle both cases systematically while
150  still hewing close to the semantics of std::optional.
151