Skip to content

Commit 4562567

Browse files
committed
[docs] LibraryEvolution: size_in_bits -> maximumFootprint.
As John pointed out to me, a maximum size guarantee is useless without a maximum alignment guarantee.
1 parent a26985d commit 4562567

File tree

1 file changed

+12
-6
lines changed

1 file changed

+12
-6
lines changed

docs/LibraryEvolution.rst

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1429,10 +1429,11 @@ except that they can be enforced by the compiler.
14291429
- ``trivial``: Promises that assignment just requires a fixed-size bit-for-bit
14301430
copy without any indirection or reference-counting operations.
14311431

1432-
- ``size_in_bits(N)``: Promises that the type is not larger than a certain
1433-
size. (It may be smaller.)
1432+
- ``maximumFootprint(sizeInBits: N, alignmentInBits: A)``: Promises that the
1433+
type's size and required alignment are at most N bits and A bits,
1434+
respectively. (Both may be smaller.)
14341435

1435-
- ``fixed_size``: Promises that the type has *some* size known at compile-time,
1436+
- ``fixedSize``: Promises that the type has *some* size known at compile-time,
14361437
allowing optimizations like promoting allocations to the stack. Only applies
14371438
to fixed-contents structs and closed enums, which can already infer this
14381439
information; the explicit annotation allows it to be enforced.
@@ -1442,14 +1443,19 @@ underscore the fact that they do not affect how a type is used at the source
14421443
level, but do allow for additional optimizations. We may also expose some of
14431444
these qualities to static or dynamic queries for performance-sensitive code.
14441445

1445-
.. note:: Previous revisions of this document contained a ``no_payload``
1446+
.. note:: Previous revisions of this document contained a ``noPayload``
14461447
assertion for enums. However, this doesn't actually offer any additional
1447-
optimization opportunities over combining ``trivial`` with ``size_in_bits``,
1448-
and the latter is more flexible.
1448+
optimization opportunities over combining ``trivial`` with
1449+
``maximumFootprint``, and the latter is more flexible.
1450+
1451+
.. note:: None of these names / spellings are final. The name "trivial" comes
1452+
from C++, though Swift's trivial is closer to C++'s "`trivially copyable`__".
14491453

14501454
All of these features need to be versioned, just like the more semantic
14511455
fragility attributes above. The exact spelling is not proposed by this document.
14521456

1457+
__ http://en.cppreference.com/w/cpp/types/is_trivially_copyable
1458+
14531459

14541460
Resilience Domains
14551461
==================

0 commit comments

Comments
 (0)