| orphan: |
|---|
Warning
This document was used in planning Swift 1.0; it has not been kept up to date and does not describe the current or planned behavior of Swift.
A namespace-scope variable (i.e. a variable not inside a function) is allowed to have an initializer, and that initializer is allowed to have side effects. Thus, we have to decide how and when the initializer runs.
WLOG, lets assume that all namespace-scope variables are mutable (and thus that immutable variables are just an optimization of the common case). Given that they can have mutable state, they cannot be "global" (in the C sense) because then they would be visible across multiple actors. Instead, the only logical semantic is for them to be actor-local data ("thread local" in the C sense) of some sort.
Given that there can be many of these variables in an address space, and very few of them may be dynamically used by any particular actor, it doesn't make sense to allocate space for all of the variables and run all of the initializers for the variables at actor-startup-time. Instead, swift should handle these as "actor associated data" (stored in a hashtable that the actor has a pointer to) and should be lazily initialized (in the absence of 'top level code', see below).
This means that if you write code like this (optionally we could require an attribute to make it clear that the value is actor local):
func foo(_ a : int) -> int { print(a) return 0 }
var x = foo(1)
var y = foo(2)
That the print statements will execute the first time that x or y is used by any particular actor.
One goal of swift is to provide a very "progressive disclosure" model of writing code and learning how to write code. Therefore, it is desirable that someone be able to start out with:
print("hello world\n")
as their first application. This requires that we support "top level code", which is code outside any function or other declaration. The counter-example of this is java, which requires someone to look at "class foo / public static void main String[]...." all of which is non-essential to the problem of writing a simple app.
Top level code is useful for a number of other things: many scripts written by unix hackers (in perl, bourne shell, ruby, etc) are really just simple command line apps that may have a few helper functions and some code that runs. While not essential, it is a great secondary goal to make these sorts of simple apps easy to write in Swift as well.
Top-Level code and lazily evaluated variable initializers don't mix well, nor does top level code and multiple actors. As such, the logical semantics are:
- Source files are partitioned into two cases: "has TLC" and "has no TLC".
- All variables defined in "has no TLC" files are allocated and initialized lazily.
- Source files that have TLC are each initialized in a deterministic order: The dependence graph of domains is respected (lower level domains are initialized before dependent ones), and the source files within a domain are initialized in some deterministic order (perhaps according to their filename or something, TBD).
- Within a source file with TLC, the TLC is run top down in deterministic order whenever the file's initializer is run. This initializer executes in the context of the "first" actor, which is created on behalf of the program by the runtime library.
- If/when some other actor refers to a variable in a file with TLC, it is allocated and initialized lazily just like globals in "has no TLC" files.
One intentional design decision in swift is to not have header files, even for public API. This is a design point like Java, but unlike C or Objective-C. Having header files for public API is nice for a couple of reasons:
- You force people to think about what they are making public, and the act of having to put it into a header makes them think about its fragility and duration over time.
- Headers are a very convenient place to get an overview of what an API is and does. In Java you get all the implementation details of a class mixed in with its public API, which makes it very difficult to understand "at a glance" what a class does.
- Headers are very useful documentation for Objective-C because we ship the headers but not the implementation of system classes. This allows "jump to definition" to go to the declaration of an API in the header, which is conveniently co-located with headerdoc.
On the other hand, headers have a number of disadvantages including:
- It is plain code duplication, with all the negative effects of it. It slows down development, can get out of synch, makes changing API more difficult, etc.
- If the prototype and implementation get out of synch, it is caught by the compiler, but this isn't true for API comments.
- Swift natively won't "need" headers, so we'd have to specifically add this capability, making the language more complicated.
- The implementation of a framework may not be in swift. If you're talking to a C or C++ framework, showing a C or C++ header when "jumping to definition" is not particularly helpful. We'd prefer to show you the synthesized API that swift code should be using.
- In Swift, the implementation of some datatype can be split across different files. Forcing all their declarations to be next to each other lexically is an arbitrary restriction.
To address the disadvantages of not having headers, we think that we should:
- Standardize on a syntax for doc comments, and bake it into the language. Mistakes using it should be diagnosed by the compiler. It should be a warning for public API to not have comments.
- There needs to be an API that dumps out the public interface for a compiled module/domain in swift syntax, slicing on a declaration. When used on a type, for example, this would show the type definition and the declaration of all of the methods on it.
- The API dumper should always dump in swift syntax, even when run on a Clang C/C++/ObjC module. It should make it very clear what the API maps to in swift syntax, so it is obvious how to use it.
- Not having headers forces us to have really great tools support/integration.