diff options
author | Paul Phillips <paulp@improving.org> | 2012-10-18 15:11:06 -0700 |
---|---|---|
committer | Paul Phillips <paulp@improving.org> | 2012-10-19 09:04:19 -0700 |
commit | 3fea5453b6a6c9451ecd6d0a93b92432b575e6cb (patch) | |
tree | 6e010951cdd253747afe18912547ca6d3fce2e6e /src/library | |
parent | 32d470d61195cbf092614711b27db396d0d54a40 (diff) | |
parent | 87c5895d4bae62f1b5bacbd145f2e0fddcccf423 (diff) | |
download | scala-3fea5453b6a6c9451ecd6d0a93b92432b575e6cb.tar.gz scala-3fea5453b6a6c9451ecd6d0a93b92432b575e6cb.tar.bz2 scala-3fea5453b6a6c9451ecd6d0a93b92432b575e6cb.zip |
Merge remote-tracking branch 'origin/2.10.x' into merge-210
* origin/2.10.x: (52 commits)
JavaUniverse
Moved @contentDiagram in Symbols
Adds lots of new documentation for TypeTags, Mirrors, Universes and more
runtime.JavaUniverse - put ungrouped members at the top
Forgotten annotation in Annotations
Diagram tweaking
Grouping for reflection and macros
fixes a typo
scala.reflect.api.Symbols documentation
Symbols docs cleanup, mostly moved to guide
scala.reflect.api.Position documentation
scala.reflect.api.StandardNames documentation
scala.reflect.api.Constants documentation
removed docs for internal TypeCreator and TreeCreator
simplified reflection docs for trees
Rearranged some reflection docs, moving things to the guide
reflection docs improvements and moves to doc page
docs for reflection and macros
SI-6509 Correct @template owners
SI-6155 Scaladoc @template diagrms
...
Conflicts:
src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
src/compiler/scala/tools/nsc/typechecker/Typers.scala
src/reflect/scala/reflect/api/Trees.scala
test/scaladoc/run/links.scala
Diffstat (limited to 'src/library')
-rw-r--r-- | src/library/scala/annotation/switch.scala | 3 | ||||
-rw-r--r-- | src/library/scala/collection/TraversableLike.scala | 7 | ||||
-rw-r--r-- | src/library/scala/concurrent/Awaitable.scala | 55 | ||||
-rw-r--r-- | src/library/scala/concurrent/package.scala | 70 | ||||
-rw-r--r-- | src/library/scala/package.scala | 3 | ||||
-rw-r--r-- | src/library/scala/reflect/ClassTag.scala | 35 | ||||
-rw-r--r-- | src/library/scala/runtime/WorksheetSupport.scala | 1 |
7 files changed, 100 insertions, 74 deletions
diff --git a/src/library/scala/annotation/switch.scala b/src/library/scala/annotation/switch.scala index a867783455..20056bc03c 100644 --- a/src/library/scala/annotation/switch.scala +++ b/src/library/scala/annotation/switch.scala @@ -9,8 +9,7 @@ package scala.annotation /** An annotation to be applied to a match expression. If present, * the compiler will verify that the match has been compiled to a - * [[http://docs.oracle.com/javase/specs/jvms/se5.0/html/Instructions2.doc14.html tableswitch]] - * or [[http://docs.oracle.com/javase/specs/jvms/se5.0/html/Instructions2.doc8.html#lookupswitch lookupswitch]] + * [[http://docs.oracle.com/javase/specs/jvms/se7/html/jvms-3.html#jvms-3.10 tableswitch or lookupswitch]] * and issue an error if it instead compiles into a series of conditional expressions. * Example usage: {{{ diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala index ce0b130b86..7849f1c544 100644 --- a/src/library/scala/collection/TraversableLike.scala +++ b/src/library/scala/collection/TraversableLike.scala @@ -271,12 +271,7 @@ trait TraversableLike[+A, +Repr] extends Any * @return a new $coll consisting of all elements of this $coll that do not satisfy the given * predicate `p`. The order of the elements is preserved. */ - def filterNot(p: A => Boolean): Repr = { - val b = newBuilder - for (x <- this) - if (!p(x)) b += x - b.result - } + def filterNot(p: A => Boolean): Repr = filter(!p(_)) def collect[B, That](pf: PartialFunction[A, B])(implicit bf: CanBuildFrom[Repr, B, That]): That = { val b = bf(repr) diff --git a/src/library/scala/concurrent/Awaitable.scala b/src/library/scala/concurrent/Awaitable.scala index 3bd7617bce..c0c688bf42 100644 --- a/src/library/scala/concurrent/Awaitable.scala +++ b/src/library/scala/concurrent/Awaitable.scala @@ -14,36 +14,47 @@ import scala.concurrent.duration.Duration +/** + * An object that may eventually be completed with a result value of type `T` which may be + * awaited using blocking methods. + * + * The [[Await]] object provides methods that allow accessing the result of an `Awaitable` + * by blocking the current thread until the `Awaitable` has been completed or a timeout has + * occurred. + */ trait Awaitable[+T] { + /** - * Await the "resolved" state of this Awaitable. - * This method should not be called directly. - * - * @param atMost - * maximum wait time, which may be negative (no waiting is done), - * [[Duration.Inf]] for unbounded waiting, or a finite positive - * duration - * @return the Awaitable itself - * @throws InterruptedException if the wait call was interrupted - * @throws TimeoutException if after waiting for the specified time this Awaitable is still not ready - * @throws IllegalArgumentException if `atMost` is [[Duration.Undefined]] + * Await the "completed" state of this `Awaitable`. + * + * '''''This method should not be called directly; use [[Await.ready]] instead.''''' + * + * @param atMost + * maximum wait time, which may be negative (no waiting is done), + * [[scala.concurrent.duration.Duration.Inf Duration.Inf]] for unbounded waiting, or a finite positive + * duration + * @return this `Awaitable` + * @throws InterruptedException if the current thread is interrupted while waiting + * @throws TimeoutException if after waiting for the specified time this `Awaitable` is still not ready + * @throws IllegalArgumentException if `atMost` is [[scala.concurrent.duration.Duration.Undefined Duration.Undefined]] */ @throws(classOf[TimeoutException]) @throws(classOf[InterruptedException]) def ready(atMost: Duration)(implicit permit: CanAwait): this.type /** - * Await and return the result of this Awaitable, which is either of type T or a thrown exception (any Throwable). - * This method should not be called directly. - * - * @param atMost - * maximum wait time, which may be negative (no waiting is done), - * [[Duration.Inf]] for unbounded waiting, or a finite positive - * duration - * @return the value if the Awaitable was successful within the specific maximum wait time - * @throws InterruptedException if the wait call was interrupted - * @throws TimeoutException if after waiting for the specified time this Awaitable is still not ready - * @throws IllegalArgumentException if `atMost` is [[Duration.Undefined]] + * Await and return the result (of type `T`) of this `Awaitable`. + * + * '''''This method should not be called directly; use [[Await.result]] instead.''''' + * + * @param atMost + * maximum wait time, which may be negative (no waiting is done), + * [[scala.concurrent.duration.Duration.Inf Duration.Inf]] for unbounded waiting, or a finite positive + * duration + * @return the result value if the `Awaitable` is completed within the specific maximum wait time + * @throws InterruptedException if the current thread is interrupted while waiting + * @throws TimeoutException if after waiting for the specified time this `Awaitable` is still not ready + * @throws IllegalArgumentException if `atMost` is [[scala.concurrent.duration.Duration.Undefined Duration.Undefined]] */ @throws(classOf[Exception]) def result(atMost: Duration)(implicit permit: CanAwait): T diff --git a/src/library/scala/concurrent/package.scala b/src/library/scala/concurrent/package.scala index e683732e41..c0d46df883 100644 --- a/src/library/scala/concurrent/package.scala +++ b/src/library/scala/concurrent/package.scala @@ -23,7 +23,7 @@ package object concurrent { * The result becomes available once the asynchronous computation is completed. * * @tparam T the type of the result - * @param body the asychronous computation + * @param body the asynchronous computation * @param execctx the execution context on which the future is run * @return the `Future` holding the result of the computation */ @@ -37,17 +37,15 @@ package object concurrent { */ def promise[T]()(implicit execctx: ExecutionContext): Promise[T] = Promise[T]() - /** Used to designate a piece of code which potentially blocks, allowing the BlockContext to adjust the runtime's behavior. + /** Used to designate a piece of code which potentially blocks, allowing the current [[BlockContext]] to adjust + * the runtime's behavior. * Properly marking blocking code may improve performance or avoid deadlocks. * - * If you have an `Awaitable` then you should use Await.result instead of `blocking`. + * Blocking on an [[Awaitable]] should be done using [[Await.result]] instead of `blocking`. * * @param body A piece of code which contains potentially blocking or long running calls. - * - * Calling this method may throw the following exceptions: - * - CancellationException - if the computation was cancelled - * - InterruptedException - in the case that a wait within the blockable object was interrupted - * - TimeoutException - in the case that the blockable object timed out + * @throws `CancellationException` if the computation was cancelled + * @throws `InterruptedException` in the case that a wait within the blocking `body` was interrupted */ @throws(classOf[Exception]) def blocking[T](body: =>T): T = BlockContext.current.blockOn(body)(scala.concurrent.AwaitPermission) @@ -67,19 +65,21 @@ package concurrent { */ object Await { /** - * Await the "resolved" state of this Awaitable. - * Invokes ready() on the awaitable, properly wrapped by a call to `scala.concurrent.blocking`. - * - * @param awaitable - * the `Awaitable` on which `ready` is to be called - * @param atMost - * maximum wait time, which may be negative (no waiting is done), - * [[Duration.Inf]] for unbounded waiting, or a finite positive - * duration - * @return the awaitable itself - * @throws InterruptedException if the wait call was interrupted - * @throws TimeoutException if after waiting for the specified time this Awaitable is still not ready - * @throws IllegalArgumentException if `atMost` is [[Duration.Undefined]] + * Await the "completed" state of an `Awaitable`. + * + * Although this method is blocking, the internal use of [[scala.concurrent.blocking blocking]] ensures that + * the underlying [[ExecutionContext]] is prepared to properly manage the blocking. + * + * @param awaitable + * the `Awaitable` to be awaited + * @param atMost + * maximum wait time, which may be negative (no waiting is done), + * [[scala.concurrent.duration.Duration.Inf Duration.Inf]] for unbounded waiting, or a finite positive + * duration + * @return the `awaitable` + * @throws InterruptedException if the current thread is interrupted while waiting + * @throws TimeoutException if after waiting for the specified time this `Awaitable` is still not ready + * @throws IllegalArgumentException if `atMost` is [[scala.concurrent.duration.Duration.Undefined Duration.Undefined]] */ @throws(classOf[TimeoutException]) @throws(classOf[InterruptedException]) @@ -87,19 +87,21 @@ package concurrent { blocking(awaitable.ready(atMost)(AwaitPermission)) /** - * Await and return the result of this Awaitable, which is either of type T or a thrown exception (any Throwable). - * Invokes result() on the awaitable, properly wrapped by a call to `scala.concurrent.blocking`. - * - * @param awaitable - * the `Awaitable` on which `result` is to be called - * @param atMost - * maximum wait time, which may be negative (no waiting is done), - * [[Duration.Inf]] for unbounded waiting, or a finite positive - * duration - * @return the value if the Awaitable was successful within the specific maximum wait time - * @throws InterruptedException if the wait call was interrupted - * @throws TimeoutException if after waiting for the specified time this Awaitable is still not ready - * @throws IllegalArgumentException if `atMost` is [[Duration.Undefined]] + * Await and return the result (of type `T`) of an `Awaitable`. + * + * Although this method is blocking, the internal use of [[scala.concurrent.blocking blocking]] ensures that + * the underlying [[ExecutionContext]] to properly detect blocking and ensure that there are no deadlocks. + * + * @param awaitable + * the `Awaitable` to be awaited + * @param atMost + * maximum wait time, which may be negative (no waiting is done), + * [[scala.concurrent.duration.Duration.Inf Duration.Inf]] for unbounded waiting, or a finite positive + * duration + * @return the result value if `awaitable` is completed within the specific maximum wait time + * @throws InterruptedException if the current thread is interrupted while waiting + * @throws TimeoutException if after waiting for the specified time `awaitable` is still not ready + * @throws IllegalArgumentException if `atMost` is [[scala.concurrent.duration.Duration.Undefined Duration.Undefined]] */ @throws(classOf[Exception]) def result[T](awaitable: Awaitable[T], atMost: Duration): T = diff --git a/src/library/scala/package.scala b/src/library/scala/package.scala index a41cdedfa9..fbb98d0582 100644 --- a/src/library/scala/package.scala +++ b/src/library/scala/package.scala @@ -95,7 +95,10 @@ package object scala { val Equiv = scala.math.Equiv type Fractional[T] = scala.math.Fractional[T] + val Fractional = scala.math.Fractional + type Integral[T] = scala.math.Integral[T] + val Integral = scala.math.Integral type Numeric[T] = scala.math.Numeric[T] val Numeric = scala.math.Numeric diff --git a/src/library/scala/reflect/ClassTag.scala b/src/library/scala/reflect/ClassTag.scala index 5c2067a548..d699e34ffc 100644 --- a/src/library/scala/reflect/ClassTag.scala +++ b/src/library/scala/reflect/ClassTag.scala @@ -5,19 +5,34 @@ import java.lang.{ Class => jClass } import scala.language.{implicitConversions, existentials} import scala.runtime.ScalaRunTime.{ arrayClass, arrayElementClass } -/** A `ClassTag[T]` wraps a runtime class (the erasure) and can create array instances. +/** + * + * A `ClassTag[T]` stores the erased class of a given type `T`, accessible via the `runtimeClass` + * field. This is particularly useful for instantiating `Array`s whose element types are unknown + * at compile time. + * + * `ClassTag`s are a weaker special case of [[scala.reflect.api.TypeTags#TypeTag]]s, in that they + * wrap only the runtime class of a given type, whereas a `TypeTag` contains all static type + * information. That is, `ClassTag`s are constructed from knowing only the top-level class of a + * type, without necessarily knowing all of its argument types. This runtime information is enough + * for runtime `Array` creation. * - * If an implicit value of type ClassTag[T] is requested, the compiler will create one. - * The runtime class (i.e. the erasure, a java.lang.Class on the JVM) of T can be accessed - * via the `runtimeClass` field. References to type parameters or abstract type members are - * replaced by the concrete types if ClassTags are available for them. + * For example: + * {{{ + * scala> def mkArray[T : ClassTag](elems: T*) = Array[T](elems: _*) + * mkArray: [T](elems: T*)(implicit evidence$1: scala.reflect.ClassTag[T])Array[T] * - * Besides accessing the erasure, a ClassTag knows how to instantiate single- and multi- - * dimensional `Arrays` where the element type is unknown at compile time. + * scala> mkArray(42, 13) + * res0: Array[Int] = Array(42, 13) * - * [[scala.reflect.ClassTag]] corresponds to a previous concept of [[scala.reflect.ClassManifest]]. + * scala> mkArray("Japan","Brazil","Germany") + * res1: Array[String] = Array(Japan, Brazil, Germany) + * }}} + * + * See [[scala.reflect.api.TypeTags]] for more examples, or the + * [[http://docs.scala-lang.org/overviews/reflection/typetags-manifests.html Reflection Guide: TypeTags]] + * for more details. * - * @see [[scala.reflect.api.TypeTags]] */ @scala.annotation.implicitNotFound(msg = "No ClassTag available for ${T}") trait ClassTag[T] extends ClassManifestDeprecatedApis[T] with Equals with Serializable { @@ -29,7 +44,7 @@ trait ClassTag[T] extends ClassManifestDeprecatedApis[T] with Equals with Serial */ def runtimeClass: jClass[_] - /** Produces a `ClassTag` that knows how to build `Array[Array[T]]` */ + /** Produces a `ClassTag` that knows how to instantiate an `Array[Array[T]]` */ def wrap: ClassTag[Array[T]] = ClassTag[Array[T]](arrayClass(runtimeClass)) /** Produces a new array with element type `T` and length `len` */ diff --git a/src/library/scala/runtime/WorksheetSupport.scala b/src/library/scala/runtime/WorksheetSupport.scala index a003bba034..016a0d04e0 100644 --- a/src/library/scala/runtime/WorksheetSupport.scala +++ b/src/library/scala/runtime/WorksheetSupport.scala @@ -4,6 +4,7 @@ import scala.runtime.ScalaRunTime.stringOf /** A utility object that's needed by the code that executes a worksheet. */ +@deprecated("SI-6458: Instrumentation logic will be moved out of the compiler.","2.10.0") object WorksheetSupport { /** The offset in the source which should be printed */ |