Skip to content

Commit

Permalink
Transcribe the rest of I.8.6.1.X signatures
Browse files Browse the repository at this point in the history
Fixes a part of stakx#9
  • Loading branch information
darthwalsh committed Feb 25, 2024
1 parent 1986903 commit 3374bee
Show file tree
Hide file tree
Showing 5 changed files with 100 additions and 0 deletions.
21 changes: 21 additions & 0 deletions docs/i.8.6.1.2-location-signatures.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
## I.8.6.1.2 Location signatures

All locations are typed. This means that all locations have a **location signature**, which defines constraints on the location, its usage, and on the usage of the values stored in the location. Any valid type signature is a valid location signature. Hence, a location signature contains a type and can additionally contain the constant constraint. The location signature can also contain **location constraints** that give further restrictions on the uses of the location. The location constraints are:

* The **init-only constraint** promises (hence, requires) that once the location has been initialized, its contents never change. Namely, the contents are initialized before any access, and after initialization, no value can be stored in the location. The contents are always identical to the initialized value (see §[I.8.2.3](i.8.2.3-classes-interfaces-and-objects.md)). This constraint, while logically applicable to any location, shall only be placed on fields (static or instance) of compound types.

* The **literal constraint** promises that the value of the location is actually a fixed value of a built-in type. The value is specified as part of the constraint. Compilers are required to replace all references to the location with its value, and the VES therefore need not allocate space for the location. This constraint, while logically applicable to any location, shall only be placed on static fields of compound types. Fields that are so marked are not permitted to be referenced from CIL (they shall be in-lined to their constant value at compile time), but are available using reflection and tools that directly deal with the metadata.

> #### CLS Rule 13:
>
> The value of a literal static is specified through the use of field initialization metadata (see [Partition II Metadata](ii.5.9-attributes-and-metadata.md)). A CLS-compliant literal must have a value specified in field initialization metadata that is of exactly the same type as the literal (or of the underlying type, if that literal is an **enum**).
>
> _[Note:_
>
> **CLS (consumer):** Must be able to read field initialization metadata for static literal fields and inline the value specified when referenced. Consumers can assume that the type of the field initialization metadata is exactly the same as the type of the literal field (i.e., a consumer tool need not implement conversions of the values).
>
> **CLS (extender):** Must avoid producing field initialization metadata for static literal fields in which the type of the field initialization metadata does not exactly match the type of the field.
>
> **CLS (framework):** Should avoid the use of syntax specifying a value of a literal that requires conversion of the value. Note that compilers can do the conversion themselves before persisting the field initialization metadata resulting in a CLS-compliant framework, but frameworks are encouraged not to rely on such implicit conversions _end note]_
_[Note:_ It might seem reasonable to provide a volatile constraint on a location that would require that the value stored in the location not be cached between accesses. Instead, CIL includes a `volatile.` prefix to certain instructions to specify that the value neither be cached nor computed using an existing cache. Such a constraint can be encoded using a custom attribute (see §[I.9.7](i.9.7-metadata-extensibility.md)), although this standard does not specify such an attribute. _end note]_
21 changes: 21 additions & 0 deletions docs/i.8.6.1.3-local-signatures.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
## I.8.6.1.3 Local signatures

A **local signature** specifies the contract on a local variable allocated during the running of a method. A local signature contains a full location signature, plus it can specify one additional constraint:

The **byref** constraint states that the content of the corresponding location is a **managed pointer**. A managed pointer can point to a local variable, parameter, field of a compound type, or element of an array. However, when a call crosses a remoting boundary (see §[I.12.5](i.12.5-proxies-and-remoting.md)) a conforming implementation can use a copy-in/copy-out mechanism instead of a managed pointer. Thus programs shall not rely on the aliasing behavior of true pointers.

In addition, there is one special local signature. The **typed reference** local variable signature states that the local will contain both a managed pointer to a location and a runtime representation of the type that can be stored at that location. A typed reference signature is similar to a byref constraint, but while the byref specifies the type as part of the byref constraint (and hence statically as part of the type description), a typed reference provides the type information dynamically. A typed reference is a full signature in itself and cannot be combined with other constraints. In particular, it is not possible to specify a **byref** whose type is **typed reference**.

The typed reference signature is actually represented as a built-in value type, like the integer and floating-point types. In the Base Class Library (see [Partition IV Library](iv.5.3-base-class-library-bcl.md)) the type is known as `System.TypedReference` and in the assembly language used in [Partition II](ii.22-metadata-logical-format-tables.md) it is designated by the keyword **typedref**. This type shall only be used for parameters and local variables. It shall not be boxed, nor shall it be used as the type of a field, element of an array, or return value.

> #### CLS Rule 14:
>
> Typed references are not CLS-compliant.
>
> _[Note:_
>
> **CLS (consumer):** There is no need to accept this type.
>
> **CLS (extender):** There is no need to provide syntax to define this type or to extend interfaces or classes that use this type.
>
> **CLS (framework):** This type shall not appear in exported members. _end note]_
3 changes: 3 additions & 0 deletions docs/i.8.6.1.4-paramater-signatures.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
## I.8.6.1.4 Parameter signatures

A **parameter signature**, defines constraints on how an individual value is passed as part of a method invocation. Parameter signatures are declared by method definitions. Any valid local signature is a valid parameter signature.
41 changes: 41 additions & 0 deletions docs/i.8.6.1.5-method-signatures.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
## I.8.6.1.5 Method signatures

A **method signature** is composed of

* a calling convention,
* the number of generic parameters, if the method is generic,
* if the calling convention specifies this is an instance method and the owning method definition belongs to a type T then the type of the `this` pointer is:
* given by the first parameter signature, if the calling convention is `instance explicit`[II.15.3](ii.15.3-calling-convention.md)),
* inferred as &T, if T is a value type and the method definition is non-virtual (§[I.8.9.7](i.8.9.7-value-type-definition.md)),
* inferred as "boxed" T, if T is a value type and the method definition is virtual (this includes method definitions from an interface implemented by T) (§[I.8.9.7](i.8.9.7-value-type-definition.md)),
* inferred as T, otherwise
* a list of zero or more parameter signatures—one for each parameter of the method— and,
* a type signature for the result value, if one is produced.

Method signatures are declared by method definitions. Only one constraint can be added to a method signature in addition to those of parameter signatures:

* The **vararg** constraint can be included to indicate that all arguments past this point are optional. When it appears, the calling convention shall be one that supports variable argument lists.

Method signatures are used in two different ways: as part of a method definition and as a description of a calling site when calling through a function pointer. In the latter case, the method signature indicates

* the calling convention (which can include platform-specific calling conventions),
* the types of all the argument values that are being passed, and
* if needed, a vararg marker indicating where the fixed parameter list ends and the variable parameter list begins.

When used as part of a method definition, the vararg constraint is represented by the choice of calling convention.

_[Note:_ a single _method implementation_ may be used both to satisfy a _method definition_ of a type and to satisfy a _method definition_ of an interface the type implements. If the type is a value type, T, then the `this` pointer in the method signature for the type's own _method definition_ is a managed pointer &T, while it is "boxed" T in the method signature associated with the interface's _method definition._ _end note]_

_[Note:_ the presence of a `this` pointer affects parameter signature/argument number pairing in CIL. If the parameter signature for the `this` pointer is inferred then the first parameter signature in the metadata is for argument number one. If there is no `this` pointer, as with static methods, or this is an `instance explicit` method, then the first parameter signature is for argument number zero. See the descriptions of the call and load function instructions in Partition III. _end note]_

> #### CLS Rule 15:
>
> The vararg constraint is not part of the CLS, and the only calling convention supported by the CLS is the standard managed calling convention.
>
> _[Note:_
>
> **CLS (consumer):** There is no need to accept methods with variable argument lists or unmanaged calling convention.
>
> **CLS (extender):** There is no need to provide syntax to declare vararg methods or unmanaged calling conventions.
>
> **CLS (framework):** Neither vararg methods nor methods with unmanaged calling conventions shall be exported externally. _end note]_
14 changes: 14 additions & 0 deletions docs/i.8.6.1.6-signature-matching.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
## I.8.6.1.6 Signature Matching

For signatures other than method signatures two signatures are said to _match_ if and only if every component type of the signature is identical in the two signatures.

Method signature matching is used when determining _hiding_ and _overriding_[I.8.10.2](i.8.10.2-method-inheritance.md), §[I.8.10.4](i.8.10.4-hiding-overriding-and-layout.md)). Two method signatures are said to _match_ if and only if:

* the calling conventions are identical;
* both signatures are either static or instance;
* the number of generic parameters is identical, if the method is generic;
* for instance signatures the type of the `this` pointer of the overriding/hiding signature is _assignable-to_[I.8.7](i.8.7-assignment-compatibility.md)) the type of the `this` pointer of the overridden/hidden signature;
* the number and type signatures of the parameters are identical; and
* the type signatures for the result are identical. _[Note:_ This includes void (§[II.23.2.11](ii.23.2.11-rettype.md)) if no value is returned. _end note]_

_[Note:_ when overriding/hiding the accessibility of items need not be identical (§[I.8.10.2](i.8.10.2-method-inheritance.md), §[I.8.10.4](i.8.10.4-hiding-overriding-and-layout.md)). _end note]_

0 comments on commit 3374bee

Please sign in to comment.