AccessControl.rst

Access Control

The general guiding principle of Swift access control:

No entity can be defined in terms of another entity that has a lower access level.

There are three levels of access: "private", "internal", and "public". Private entities can only be accessed from within the source file where they are defined. Internal entities can be accessed anywhere within the module they are defined. Public entities can be accessed from anywhere within the module and from any other context that imports the current module.

The names public and private have precedent in many languages; internal comes from C#. In the future, public may be used for both API and SPI, at which point we may design additional annotations to distinguish the two.

By default, most entities in a source file have internal access. This optimizes for the most common case—a single-target application project—while not accidentally revealing entities to clients of a framework module.

• Rules
  • Globals and Members
  • Protocols
  • Structs, Enums, and Classes
  • Types
• Runtime Guarantees
  • Interaction with Objective-C
• Non-Goals: "class-only" and "protected"
• Potential Future Directions

Rules

Access to a particular entity is considered relative to the current access context. The access context of an entity is the current file (if private), the current module (if internal), or the current program (if public). A reference to an entity may only be written within the entity's access context.

If a particular entity is not accessible, it does not appear in name lookup, unlike in C++. However, access control does not restrict access to members via runtime reflection (where applicable), nor does it necessarily restrict visibility of symbols in a linked binary.

Globals and Members

A global function, constant, or variable may have any access level less than or equal to the access level of its type. That is, a private constant can have public type, but not the other way around.

Accessors for variables have the same access level as their associated variable. The setter may be explicitly annotated with an access level less than or equal to the access level of the variable; this is written as private(set) or internal(set) before the var introducer.

An initializer, method, subscript, or property may have any access level less than or equal to the access level of its type (including the implicit 'Self' type), with a few additional rules:

• If the type's access level is private, the access level of members defaults to private. If the type's access level is internal or public, the access level of members defaults to internal.
• If a member is used to satisfy a protocol requirement, its access level must be at least as high as the protocol conformance's; see :ref:`Protocols` below.
• If an initializer is required by a superclass, its access level must be at least as high as the access level of the subclass itself.
• Accessors for subscripts follow the same rules as accessors for variables.
• A member may be overridden whenever it is accessible.

The implicit memberwise initializer for a struct has the minimum access level of all of the struct's stored properties, except that if all properties are public the initializer is internal. The implicit no-argument initializer for structs and classes follows the default access level for the type.

Currently, enum cases always have the same access level as the enclosing enum.

Deinitializers are only invoked by the runtime and do not nominally have access. Internally, the compiler represents them as having the same access level as the enclosing type.

Protocols

A protocol may have any access level less than or equal to the access levels of the protocols it refines. That is, a private ExtendedWidget protocol can refine an public Widget protocol, but not the other way around.

The access level of a requirement is the access level of the enclosing protocol, even when the protocol is public. Currently, requirements may not be given a lower access level than the enclosing protocol.

Swift does not currently support private protocol conformances, so for runtime consistency, the access level of the conformance of type T to protocol P is equal to the minimum of T's access level and P's access level; that is, the conformance is accessible whenever both T and P are accessible. This does not change if the protocol is conformed to in an extension. (The access level of a conformance is not currently reflected in the source, but is a useful concept for applying restrictions consistently.)

All members used to satisfy a conformance must have an access level at least as high as the conformance's. This ensures consistency between views of the type; if any member has a lower access level than the conformance, then the member could be accessed anyway through a generic function constrained by the protocol.

Note

This rule disallows an internal member of a protocol extension to satisfy a public requirement for a public type. Removing this limitation is not inherently unsafe, but (a) may be unexpected given the lack of explicit reference to the member, and (b) results in references to non-public symbols in the current representation.

A protocol may be used as a type whenever it is accessible. A nominal can conform to a protocol whenever the protocol is accessible.

Structs, Enums, and Classes

A struct, enum, or class may be used as a type whenever it is accessible. A struct, enum, or class may be extended whenever it is accessible.

A class may be subclassed whenever it is accessible. A class may have any access level less than or equal to the access level of its superclass.

Members in an extension have the same default access level as members declared within the extended type. However, an extension may be marked with an explicit access modifier (e.g. private extension), in which case the default access level of members within the extension is changed to match.

Extensions with explicit access modifiers may not add new protocol conformances, since Swift does not support private protocol conformances (see :ref:`Protocols` above).

A type may conform to a protocol with lower access than the type itself.

Types

A nominal type's access level is the same as the access level of the nominal declaration itself. A generic type's access level is the minimum of the access level of the base type and the access levels of all generic argument types.

A tuple type's access level is the minimum of the access levels of its elements. A function type's access level is the minimum of the access levels of its input and return types.

A typealias may have any access level up to the access level of the type it aliases. That is, a private typealias can refer to an public type, but not the other way around. This includes associated types used to satisfy protocol conformances.

Runtime Guarantees

Non-public members of a class or extension will not be seen by subclasses or other extensions from outside the module. Therefore, members of a subclass or extension will not conflict with or inadvertently be considered to override non-accessible members of the superclass.

Both private and internal increase opportunities for devirtualization, though it is still possible to put a subclass of a private class within the same file.

Most information about a non-public entity still has to be put into a module file for now, since we don't have resilience implemented. This can be improved later, and is no more revealing than the information currently available in the runtime for pure Objective-C classes.

Interaction with Objective-C

If an entity is exposed to Objective-C, most of the runtime guarantees and optimization opportunities go out the window. We have to use a particular selector for members, everything can be inspected at runtime, and even a private member can cause selector conflicts. In this case, access control is only useful for discipline purposes.

Members explicitly marked private are not exposed to Objective-C unless they are also marked @objc (or @IBAction or similar), even if declared within a class implicitly or explicitly marked @objc.

Any public entities will be included in the generated header. In an application or unit test target, internal entities will be exposed as well.

Non-Goals: "class-only" and "protected"

This proposal omits two forms of access control commonly found in other languages, a "class-implementation-only" access (often called "private"), and a "class and any subclasses" access (often called "protected"). We chose not to include these levels of access control because they do not add useful functionality beyond private, internal, and public.

"class-only"

If "class-only" includes extensions of the class, it is clear that it provides no protection at all, since a class may be extended from any context where it is accessible. So a hypothetical "class-only" must already be limited with regards to extensions. Beyond that, however, a "class-only" limit forces code to be declared within the class that might otherwise naturally be a top-level helper or an extension method on another type.

private serves the proper use case of limiting access to the implementation details of a class (even from the rest of the module!) while not requiring that all of those implementation details be written lexically inside the class.

"protected"

"protected" access provides no guarantees of information hiding, since any subclass can now access the implementation details of its superclass---and expose them publicly, if it so chooses. This interacts poorly with our future plans for resilient APIs. Additionally, it increases the complexity of the access control model for both the compiler and for developers, and like "class-only" it is not immediately clear how it interacts with extensions.

Though it is not compiler-enforced, members that might be considered "protected" are effectively publicly accessible, and thus should be marked public in Swift. They can still be documented as intended for overriding rather than for subclassing, but the specific details of this are best dealt with on a case-by-case basis.

Potential Future Directions

• Allowing private or internal protocol conformances, which are only accessible at compile-time from a particular access context.
• Limiting particular capabilities, such as marking something final(public) to restrict subclassing or overriding outside of the current module.
• Allowing the Swift parts of a mixed-source framework to access private headers.
• Revealing internal Swift API in a mixed-source framework in a second generated header.
• Levels of public, for example public("SPI").
• Enum cases less accessible than the enum.
• Protocol requirements less accessible than the protocol.