docs/archive/NamespaceLevelVarsAndTopLevelCode.rst - third_party/swift - Git at Google

 :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.

 Mutable Namespace-Scope Variable Declarations
 =============================================

 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.


 Top Level Code
 --------------

 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:

 1. Source files are partitioned into two cases: "has TLC" and "has no TLC".
 2. All variables defined in "has no TLC" files are allocated and initialized
    lazily.
 3. 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).
 4. 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.
 5. 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.

 On "Not Having Headers"
 -----------------------

 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:

 1. 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.
 2. 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.
 3. 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:

 1. 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.
 2. If the prototype and implementation get out of synch, it is caught by the
    compiler, but this isn't true for API comments.
 3. Swift natively won't "need" headers, so we'd have to specifically add this
    capability, making the language more complicated.
 4. 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.
 5. 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:

 1. 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.
 2. 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.
 3. 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.
 4. Not having headers forces us to have really great tools support/integration.
	: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.

	Mutable Namespace-Scope Variable Declarations
	=============================================

	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.


	Top Level Code
	--------------

	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:

	1. Source files are partitioned into two cases: "has TLC" and "has no TLC".
	2. All variables defined in "has no TLC" files are allocated and initialized
	lazily.
	3. 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).
	4. 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.
	5. 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.

	On "Not Having Headers"
	-----------------------

	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:

	1. 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.
	2. 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.
	3. 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:

	1. 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.
	2. If the prototype and implementation get out of synch, it is caught by the
	compiler, but this isn't true for API comments.
	3. Swift natively won't "need" headers, so we'd have to specifically add this
	capability, making the language more complicated.
	4. 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.
	5. 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:

	1. 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.
	2. 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.
	3. 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.
	4. Not having headers forces us to have really great tools support/integration.