Constructors and factories

Documentation status: architecture — see Maturity and evidence.

Constructors are represented separately from ordinary methods in the ABI publication model. Their canonical identity is derived from the declaring Runtime type and constructor parameter types; there is no logical source return type in the constructor signature.

At the ABI boundary, successful construction yields an opaque Runtime object reference. The generated .NET layer converts that reference into the appropriate managed wrapper.

managed construction
      |
      v
constructor MethodId
      |
      v
Runtime object reference
      |
      v
generated managed object

Public programming model

Generated APIs should expose construction in a language-natural form, for example a constructor or a named factory depending on the publication model:

var session = new Session(options);

or:

var session = Session.Create(options);

The exact generated spelling is package/release dependent. Application documentation should follow the generated SDK rather than manually invoking constructor IDs.

Constructor overloads

Constructor overloads are distinguished by their parameter types. The publication generator calculates stable constructor identities before emitting the target binding, preventing target-language name mangling from becoming the Runtime contract.

Defaults and optional values

Documentation metadata can carry normalized default values, and target generators may use published defaults when they can be represented safely in the target language.

A binding must not invent a managed default that changes Runtime semantics. When a default cannot be represented faithfully, the generated call should require the explicit argument or expose a generated overload whose behavior is defined by the publication contract.

Ownership after construction

A newly constructed Runtime object has a lifetime independent from the temporary argument buffers used by the call. The generated wrapper is responsible for carrying the Runtime reference and eventually releasing it according to the binding lifetime contract.

See Lifetime and release.