NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Signatures

Signatures are the part of a contract that can be checked and automatically enforced. Signatures are formed by adding constraints to types and other signatures. A constraint is a limitation on the use of or allowed operations on a value or location. Example constraints would be whether a location can be overwritten with a different value or whether a value can ever be changed.

All locations have signatures, as do all values. Assignment compatibility requires that the signature of the value, including constraints, is compatible with the signature of the location, including constraints. There are four fundamental kinds of signatures: type signatures, location signatures, parameter signatures, and method signatures.

CLS Rule 10: All types appearing in a signature must be CLS-compliant.

CLS Rule 11: The visibility and accessibility of types and members must be such that types in the signature of any member must be visible and accessible whenever the member itself is visible and accessible. For example, a public method that is visible outside its assembly must not have an argument whose type is visible only within the assembly.

CLS (consumer): need not accept types whose members violate these rules.

CLS (extender): need not provide syntax to violate these rules.

CLS (framework): must not violate this rule in its exposed types and their members.

Type Signatures

Type signatures define the constraints on a value and its usage. A type, by itself, is a valid type signature. Only one constraint can be added to a type to produce a type signature:

The type signature of a value cannot be determined by examining the value or even by knowing the class type of the value. The type signature of a value is derived from the location signature (see below) of the location from which the value is loaded. Normally the type signature of a value is the type in the location signature from which the value is loaded. If the location signature includes the constant constraint, then the type signature of the value loaded from that location also includes the constant constraint.

Note: The constant constraint cannot be expressed in V1 of the NGWS runtime.

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 may additionally contain the constant constraint. The location signature may also contain location constraints that give further restrictions on the uses of the location. The location constraints are:

Note: In V1 the init-only constraint is allowed only on fields of compound types, and the literal constraints is allowed only on static fields of compound types.

Note: In V1 the volatile constraint is not supported. Instead, the IL instruction set encodes specific accesses that must be handled specially.

Init-only describes a location into which a new value cannot be stored. Volatile describes a location that is changing outside the control of this portion of the program. Constant declares that the values loaded from the location are not to be used to make modifications to the value. Any or all of these constraints can be specified as part of a location signature.

Consider a location whose type is “Array of 32-bit signed integers.” If the location signature contains the init-only constraint, then the location always contains a reference to the same array in memory, but this reference can be used to store different integers within that array. If the location signature contains the constant constraint (actually a type signature constraint, but stored in the location signature) then over time, the location may contain references to different arrays. However, at any given time the current array reference should not be used to change any of the integers stored within the array. If the location signature contains the volatile constraint, then any array reference read from this location should not be cached, i.e. every reference in the source code to the location should re-load the array reference from the location.

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 may specify one additional constraint:

The byref constraint states that the content of the corresponding location is a managed pointer. A managed pointer may point either to a local variable, parameter, field of a compound type, or element of an array. Managed pointers must be reported to the garbage collector, since the location to which they refer may be moved.

Note: While strictly speaking the byref constraint means that a managed pointer is to be passed, when the call crosses a remoting boundary (see Proxies, Contexts, and Remoting) this may be implemented by a copy-in/copy-out mechanism. Thus programs must not rely on the aliasing behavior of true pointers.

In addition, there is one special local signature. The typed reference local signature states that the local will contain both a managed pointer to a location and the a runtime representation of the type that may 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 as part of the type description), a typed reference provides the type information dynamically. Hence 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.

Note: The typed reference signature is provided as a built-in value type in V1. In the Base Class Library, the type is known as System.TypedReference and in the assembler it is designated by the keyword typedref. This type can only be used for parameters and local variables. It is illegal to box it, to use it as the type of a field of a type, element of an array, return value, etc.

CLS Rule 12: Typed references are not CLS-compliant.

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 may not appear in exposed members.

Parameter Signatures

Parameter signatures define 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.

Method Signatures

Method signatures are composed of

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

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

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

CLS Rule 13: The varargs constraint is not part of the CLS, and the only calling convention supported by the CLS is the standard managed calling convention.

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 varargs methods or unmanaged calling conventions.

CLS (framework): neither varargs methods nor methods with unmanaged calling conventions may be exposed externally.