Skeleton API for lazy library loading.

dart/sdk/lib/core/load_async.dart

+// Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/**
+ * Indicates that loading of [libraryName] is deferred.
+ *
+ * Applies to library imports.
+ *
+ * Example usage:
+ *
+ * [:
+ * @DeferLoad('com.example.foo')
+ * import 'foo.dart' as foo;
+ *
+ * void main() {
+ *   foo.method(); // Warning: foo may not have been loaded.
+ *   load('com.example.foo').then(onFooLoaded);
+ * }
+ *
+ * @OnLibraryLoaded('com.example.foo')

[kasperl, 2013/01/07 12:18:07]

Maybe this would be better as WhenLibraryLoaded because it really isn't an event
handler itself. Not sure.

[Sean Eagan, 2013/01/14 15:57:52]

Could the libraryName possibly default to the name used in the "as" clause of
the import statement if there is one, e.g. "foo" in this case?

[ahe, 2013/01/14 16:17:37]

It is the name of the library, not the prefix. This allows the VM to detect
multiple libraries with the same name, without loading the sources eagerly
(which we want to avoid).

+ * void onFooLoaded(_) {
+ *   foo.method(); // No warning.
+ * }
+ * :]
+ */

[gbracha, 2013/01/07 17:40:15]

1. The behavior of this annotation should be properly specified. Examples do not
constitute specification.
2. This is a language feature slipping in as an annotation, as it changes what
warnings are given.  If this is what we want, we should make it part of the
language spec.

+class DeferLoad {
+  final String libraryName;
+
+  const DeferLoad(this.libraryName);
+}
+
+/**
+ * Indicates that an element is not called until [libraryName] has
+ * been loaded.
+ *
+ * Applies to library declarations, classes, and functions.
+ */

[gbracha, 2013/01/07 17:40:15]

1. The comment says nothing about the semantics of this annotation.
2. From the examples, I conclude that this suppresses warnings generated by
DeferLoad. This should be stated here.
3. More substantively, this is a language change, as it effects what warnings
are generated. This is a slippery slope with magical annotations having language
effects.

[ahe, 2013/01/08 07:19:48]

I agree. What do you suggest we do instead?

+class OnLibraryLoaded {
+  final String libraryName;
+
+  const OnLibraryLoaded(this.libraryName);
+}
+
+/**
+ * Ensure that [libraryName] has been loaded.
+ *
+ * The returned future if this invocation of [load] caused the library

[floitsch, 2013/02/18 13:22:35]

Comment seems incomplete.

+ * to be loaded.
+ */
+external Future<bool> load(String libraryName, {String uri});

[Sean Eagan, 2013/01/14 15:57:52]

Does this Future throw some sort of error, e.g. LibraryLoadException, if the
library could not be loaded?

Does the libraryName have to correspond to an @DeferLoad annotation directly in
this library, or could it also be from an @DeferLoad in a library which this
library imports or exports?

[ahe, 2013/01/14 16:17:37]

Yes.
It can be in a different library, which is another reason to use library names,
not prefixes above. 

[floitsch, 2013/02/18 13:22:35]

a top-level "load" sounds dangerous to me.