Skip to content

Commit

Permalink
Propose fixing some typos
Browse files Browse the repository at this point in the history
  • Loading branch information
jeis2497052 committed Feb 15, 2018
1 parent 33996de commit 0945239
Show file tree
Hide file tree
Showing 7 changed files with 34 additions and 37 deletions.
27 changes: 13 additions & 14 deletions docs/ABI/GenericSignature.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,14 +41,14 @@ Consider the following generic signature:
The constraint `C1.Element: Equatable` is redundant (because it can be proven based on `C1.Element == C2.Element` and `C2.Element: Equatable`). Similarly, `C2.Element: Equatable` is redundant (based on `C1.Element == C2.Element` and `C1.Element: Equatable`). Either one of these constraints can be removed without changing the semantics of the generic signature, and the resulting generic signature will be minimal (there are no redundant constraints that remain). As such, there are two minimal generic signatures that describe this set of constraints:

```swift
<C1, C2 where C1: Collection, C2: Collection, C1.Element: Equatable,
<C1, C2 where C1: Collection, C2: Collection, C1.Element: Equatable,
C1.Element == C2.Element>
```

and

```swift
<C1, C2 where C1: Collection, C2: Collection, C1.Element == C2.Element,
<C1, C2 where C1: Collection, C2: Collection, C1.Element == C2.Element,
C2.Element: Equatable>
```

Expand All @@ -60,19 +60,19 @@ A generic signature is *canonical* when each of its constraints is [canonical](#

1. Generic type parameters are listed first
ordered by [type parameter ordering](#type-parameter-ordering)
2. Constraints follow, ordered first by the
[type parameter ordering](#type-parameter-ordering) of the left-hand
2. Constraints follow, ordered first by the
[type parameter ordering](#type-parameter-ordering) of the left-hand
operand and then by constraint kind. The left-hand side of a constraint
is always a type parameter (call it `T`).
Constraints are ordered as follows:
1. A superclass constraint `T: C`, where `C` is a class.
2. A layout constraint (e.g., `T: some-layout`), where the right-hand
side is `AnyObject` or one of the non-user-visible layout constraints
side is `AnyObject` or one of the non-user-visible layout constraints
like `_Trivial`.
3. Conformance constraints `T: P`, where `P` is a protocol. The
conformance constraints for a given type parameter `T` are further
3. Conformance constraints `T: P`, where `P` is a protocol. The
conformance constraints for a given type parameter `T` are further
sorted using the [protocol ordering](#protocol-ordering).
4. A same-type constraint `T == U`, where `U` is either a type parameter
4. A same-type constraint `T == U`, where `U` is either a type parameter
or a concrete type.

### Type parameter ordering
Expand Down Expand Up @@ -117,7 +117,7 @@ Each equivalence class has a corresponding *anchor*, which is a type parameter t

A layout or conformance constraint is canonical when its left-hand side is the anchor of its equivalence class. A superclass constraint is canonical when its left-hand side is the anchor of its equivalence class and its right-hand side is a canonical concrete (class) type. Same-type constraint canonicalization is discussed in detail in the following section, but some basic rules apply: the left-hand side is always a type parameter, and the right-hand side is either a type parameter that follows the left-hand side (according to the [type parameter ordering](#type-parameter-ordering)) or is a canonical concrete type.

### Same-type constaints
### Same-type constraints

The canonical form of superclass, layout, and conformance constraints are directly canonicalizable once the equivalence classes are known. Same-type constraints, on the other hand, are responsible for forming those equivalence classes. Let's expand our running example to include a third `Collection`:

Expand All @@ -138,13 +138,13 @@ or
C1.Element == C2.Element, C2.Element == C3.Element
```

or
or

```swift
C1.Element == C3.Element, C2.Element == C3.Element
```

All of these sets of constraints have the same effect (i.e., form the same equivalence class), but the second one happens to be the canonical form.
All of these sets of constraints have the same effect (i.e., form the same equivalence class), but the second one happens to be the canonical form.

The canonical form is determined by first dividing all of the types in the same equivalence class into distinct components. Two types `T1` and `T2` are in the same component if the same type constraint `T1 == T2` can be proven true based on other known constraints in the generic signature (i.e., if `T1 == T2` would be redundant). For example, `C1.Element` and `C1.SubSequence.Elemenent` are in the same component, because `C1: Collection` and the `Collection` protocol contains the constraint `Element == SubSequence.Element`. However, `C1.Element` and `C2.Element` are in different components.

Expand All @@ -162,15 +162,15 @@ For the first case, consider a function that operates on `String` collections:
```swift
func manyStrings<C1: Collection, C2: Collection, C3: Collection>(
c1: C1, c2: C2, c3: C3)
where C1.Element == String, C1.Element == C2.Element,
where C1.Element == String, C1.Element == C2.Element,
C1.Element == C3.SubSequence.Element
{ }
```

The minimal canonical generic signature for this function is:

```swift
<C1, C2, C3 where C1: Collection, C2: Collection, C3: Collection,
<C1, C2, C3 where C1: Collection, C2: Collection, C3: Collection,
C1.Element == String, C2.Element == String, C3.Element == String>
```

Expand All @@ -189,4 +189,3 @@ protocol Collection: Sequence where SubSequence: Collection {
```

This protocol introduces a number of constraints: `Self: Sequence` (stated as inheritance), `Self.SubSequence: Collection` (in the protocol where clause), `Self.Indices: Collection` (associated type declaration) and `Self.Indices.Element == Index` (associated type where clause). These constraints, which are directly implied by `Self: Collection`, form the *requirement signature* of a protocol. As with other generic signatures used for the ABI, the requirement signature is minimal and canonical according to the rules described elsewhere in this document.

8 changes: 4 additions & 4 deletions docs/ABI/KeyPaths.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,15 @@ way that it can be transformed in-place into a key path object with a one-time
initialization in the common case where the entire path is fully specialized
and crosses no resilience boundaries.

## ABI Concerns For Key Paths
## ABI Concerns For Key Paths

For completeness, this document describes the layout of both key path objects
and patterns; note however that the instantiated runtime layout of key path
objects is an implementation detail of the Swift runtime, and *only key path
patterns* are strictly ABI, since they are emitted by the compiler. The
runtime has the freedom to change the runtime layout of key path objects, but
will have to maintain the ability to instantiate from key path patterns emitted
by previous ABI-stable versions of the Swift complier.
by previous ABI-stable versions of the Swift compiler.

## Key Path Objects

Expand Down Expand Up @@ -202,10 +202,10 @@ Value in bit 30&29 | Description
`2*sizeof(Int)` | **Is Equal**
`3*sizeof(Int)` | **Hash**

The *destroy* function, if not null, has signature
The *destroy* function, if not null, has signature
`@convention(thin) (UnsafeMutableRawPointer) -> ()` and is invoked to
destroy the captures when the key path object is deallocated.

The *copy* function has signature
`@convention(thin) (_ src: UnsafeRawPointer,
_ dest: UnsafeMutableRawPointer) -> ()`
Expand Down
8 changes: 4 additions & 4 deletions docs/DebuggingTheCompiler.rst
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@ There is another useful script to view the CFG of a disassembled function:
It splits a disassembled function up into basic blocks which can then be
used with viewcfg::

(lldb) disassemble
(lldb) disassemble
<copy-paste output to file.s>
$ blockifyasm < file.s | viewcfg

Expand Down Expand Up @@ -458,7 +458,7 @@ That will write the types log to the file passed to the -f option.

**NOTE** Module loading can happen as a side-effect of other operations in lldb
(e.g. the "file" command). To be sure that one has enabled logging before /any/
module loading has occured, place the command into either::
module loading has occurred, place the command into either::

~/.lldbinit
$PWD/.lldbinit
Expand All @@ -483,8 +483,8 @@ following non-exhaustive list of state:
1. The unparsed, textual expression passed to the compiler.
2. The parsed expression.
3. The initial SILGen.
4. SILGen after SILLinking has occured.
5. SILGen after SILLinking and Guaranteed Optimizations have occured.
4. SILGen after SILLinking has occurred.
5. SILGen after SILLinking and Guaranteed Optimizations have occurred.
6. The resulting LLVM IR.
7. The assembly code that will be used by the JIT.

Expand Down
6 changes: 3 additions & 3 deletions docs/Generics.rst
Original file line number Diff line number Diff line change
Expand Up @@ -747,7 +747,7 @@ The exact syntax of the @_specialize function attribute is defined as: ::
@_specialize(exported: false, kind: partial, where K: _Trivial64)
func dictFunction<K, V>(dict: Dictionary<K, V>) {
}

If 'exported' is set, the corresponding specialization would have a public
visibility and can be used by clients. If 'exported' is omitted, it's value
is assumed to be 'false'.
Expand All @@ -757,7 +757,7 @@ produce an error if you forget to specify the type for some of the generic
parameters in the 'where' clause. If 'kind' is 'partial' it means a partial
specialization. If 'kind' is omitted, its value is assumed to be 'full.

The requirements in the where clause may be same-type constaints like 'T == Int',
The requirements in the where clause may be same-type constraints like 'T == Int',
but they may also specify so-called layout constraints like 'T: _Trivial'.

The following layout constraints are currently supported:
Expand All @@ -773,7 +773,7 @@ The following layout constraints are currently supported:
exactly 'SizeInBits' bits.
* _TrivialAtMost(SizeInBits) - like _Trivial, but the size of the type should
be at most 'SizeInBits' bits.


Existential Types and Generics
------------------------------
Expand Down
8 changes: 4 additions & 4 deletions docs/SIL.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3188,7 +3188,7 @@ executing the ``begin_apply``) were being "called" by the ``yield``:
- The convention attributes are the same as the parameter convention
attributes, interpreted as if the ``yield`` were the "call" and the
``begin_apply`` marked the entry to the "callee". For example,
an ``@in Any`` yield transferrs ownership of the ``Any`` value
an ``@in Any`` yield transfers ownership of the ``Any`` value
reference from the coroutine to the caller, which must destroy
or move the value from that position before ending or aborting the
coroutine.
Expand Down Expand Up @@ -3714,7 +3714,7 @@ destructure_struct
// %0 must be a struct of type $S
// %eltN must have the same type as the Nth field of $S

Given a struct, split the struct into its constituant fields.
Given a struct, split the struct into its constituent fields.

object
``````
Expand All @@ -3729,7 +3729,7 @@ object

Constructs a statically initialized object. This instruction can only appear
as final instruction in a global variable static initializer list.

ref_element_addr
````````````````
::
Expand Down Expand Up @@ -4026,7 +4026,7 @@ container may use one of several representations:
Said value might be replaced with one of the _addr instructions above
before IR generation.
The following instructions manipulate "loadable" opaque existential containers:

* `init_existential_value`_
* `open_existential_value`_
* `deinit_existential_value`_
Expand Down
12 changes: 5 additions & 7 deletions docs/StandardLibraryProgrammersManual.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ TODO: Should this subsume or link to [AccessControlInStdlib.rst](https://github.
1. Library Organization
1. What files are where
1. Brief about CMakeLists
1. Brief about GroupInfo.json
1. Brief about GroupInfo.json
1. What tests are where
1. Furthermore, should there be a split between whitebox tests and blackbox tests?
1. What benchmarks are where
Expand All @@ -23,7 +23,7 @@ TODO: Should this subsume or link to [AccessControlInStdlib.rst](https://github.
1. Protocol hierarchy
1. Customization hooks
1. Use of classes, COW implementation, buffers, etc
1. Compatiblity, `@available`, etc.
1. Compatibility, `@available`, etc.
1. Resilience, ABI stability, `@_inlineable`, `@_versioned`, etc
1. Strings and ICU
1. Lifetimes
Expand Down Expand Up @@ -75,8 +75,8 @@ if _fastPath(...) {
...
if _fastPath(...) {
// 9% of the time we execute this: very conservative inlining
...
return
...
return
}

// 1% of the time we execute this: very conservative inlining
Expand All @@ -87,7 +87,7 @@ return
*NOTE: these are due for a rename and possibly a redesign. They conflate multiple notions that don’t match the average standard library programmer’s intuition.*


#### `_onFastPath`
#### `_onFastPath`

This should be rarely used. It informs the SIL optimizer that any code dominated by it should be treated as the innermost loop of a performance critical section of code. It cranks optimizer heuristics to 11. Injudicious use of this will degrade performance and bloat binary size.

Expand Down Expand Up @@ -170,5 +170,3 @@ The standard library utilizes thread local storage (TLS) to cache expensive comp
3. If the field is not trivially destructable, update `_destroyTLS` to properly destroy the value.
See [ThreadLocalStorage.swift](https://github.com/apple/swift/blob/master/stdlib/public/core/ThreadLocalStorage.swift) for more details.
2 changes: 1 addition & 1 deletion docs/refactoring/SwiftLocalRefactoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,7 @@ Though a little more complex than its counterpart in the aforementioned String
Localization refactoring, this implementation is self-explaining too. Lines 3
to 4 check the kind of the given range, which has to be a single expression
to proceed with the extraction. Lines 5 to 7 ensure the extracted expression has
a well-formed type. Further conditions that need to be checked are ommitted in
a well-formed type. Further conditions that need to be checked are omitted in
the example for now. Interested readers can refer to [Refactoring.cpp] for
more details. For the code change part, we can use the same [RangeInfo] instance
to emit textual edits:
Expand Down

0 comments on commit 0945239

Please sign in to comment.