init

Author: TiarkRompf

LICENSE.md

@@ -0,0 +1,27 @@
+Copyright (c) 2014-2015 Purdue University
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name of the EPFL nor the names of its contributors
+      may be used to endorse or promote products derived from this software
+      without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,113 @@
+The Great Escape
+================
+
+First-class service is nice. But if everybody rides first class, it stops being fun.
+
+This Scala compiler plug-in exposes a programming model to enforce a _no-escape_ policy for certain objects.
+
+There are many potential uses:
+
+- Effects: 
+    Objects can serve as capabilities. But we must limit the scope of capabilities to retain control. Compare to Monads, which do not compose well. 
+- Region based memory:
+    Deallocate and/or reuse memory in a timely manner (note that we do not aim to do this for _all_ allocations, just for big chunks).
+- Resource control:
+    Ensure that resources such as file handles are properly closed.
+- Staging:
+    Scope extrusion. We must limit the scope of binders to guarantee well-typed generated code.
+- Distributed systems:
+    We do not want to serialize large data by accident (see Spores).
+
+
+A High-Level Example
+--------------------
+
+If an expression has type `A @safe(x)` it will not leak symbol `x`.
+
+If a function has type `A => B @safe(%)`, it will not leak its argument.
+Think of this as a dependent function type `(x:A) => B @safe(x)`.
+
+    // For exception handling, we would like to enforce that
+    // exceptions can only be raised within a try/catch block.
+
+    def trycatch(f: (Exception => Nothing) => Unit @safe(%)): Unit
+
+    // The closure passed to trycatch may not leak its argument.
+
+    trycatch { raise =>
+      raise(new Exception)  // ok: raise cannot escape
+    }
+
+    // Inside a try block we can use `raise` in safe positions,
+    // but not in unsafe ones, where it could be leaked.
+
+    def safeMethod(f: () => Any): Int @safe(f)
+    def unsafeMethod(f: () => Any): Int
+
+    trycatch { raise =>
+      safeMethod { () =>
+        raise(new Exception)  // ok: closure is safe
+      }
+      unsafeMethod { () =>
+        raise(new Exception)  // not ok
+      }
+    }
+
+See the [test suite](library/src/test/scala/scala/tools/escape) for complete code.
+
+
+Practical Restrictions
+----------------------
+
+Consider the following example:
+
+    def map[A,B](xs: List[A])(f: A => B): List[B] @safe(f) = {
+      val b = new Builder[B]
+      xs foreach (x => b += f(x))
+      b.result
+    }
+
+We are not leaking `f`, but we _are_ leaking objects returned
+from calling `f`.
+
+It is no problem to use `map` like this:
+
+    map(xs) { x =>
+      if (x > 0) x else raise(new Exception)
+    }
+
+But we need to be careful about cases where
+we could transitively leak `raise`, e.g. as part of
+another closure:
+
+    map(xs) { x =>
+      () => raise(new Exception)
+    }
+
+The design decision here is to disallow this case.
+
+Extensions to _n-level_ safety are conceivable.
+
+
+Rationale and Background
+------------------------
+
+The concept of higher-order and first-class language constructs goes hand in hand. In a higher-order language, many things are first-class: functions, mutable references, etc.
+
+Being first-class means that there are no restrictions on how an object may be used. Functions can be passed to other functions as arguments and returned from other functions. First class reference cells may hold functions or other reference cells.
+
+Lexical scope is central to most modern programming languages. First-class functions _close over_ their defining scope. Hence they are also called closures.
+
+While programming with first-class objects is incredibly useful, it is sometimes _too_ powerful, and one loses some useful guarantees.
+
+For example, in a language without closures, function calls follow a strict stack discipline. A local variable's lifetime ends when the function returns and its space can be reclaimed. Contrast this with higher-order languages, which allocate closure records on the heap. The lifetime of a variable may be indefinite if it is captured by a closure.
+
+Binding the lifetime of (certain -- not all) objects is important. So maybe not all objects should be first class?
+
+After all, we want first class to be an exclusive club, with tightly regulates access. 
+
+
+Current Status
+--------------
+
+Early development and proof of concept. Do not expect too much, but feel free to contribute!

build.sbt

@@ -0,0 +1,55 @@
+import com.typesafe.tools.mima.plugin.{MimaPlugin, MimaKeys}
+import Keys.{`package` => packageTask }
+import com.typesafe.sbt.osgi.{OsgiKeys, SbtOsgi}
+
+// plugin logic of build based on https://github.com/retronym/boxer
+
+lazy val commonSettings = scalaModuleSettings ++ Seq(
+  repoName                   := "scala-escape",
+  organization               := "org.scala-lang.plugins",
+  version                    := "1.0.1-SNAPSHOT",
+  scalaVersion               := "2.11.4",
+  snapshotScalaBinaryVersion := "2.11.4",
+  scalacOptions ++= Seq(
+    "-deprecation",
+    "-feature")
+)
+
+lazy val root = project.in( file(".") ).settings( publishArtifact := false ).aggregate(plugin, library).settings(commonSettings : _*)
+
+lazy val plugin = project settings (scalaModuleOsgiSettings: _*) settings (
+  name                   := "scala-escape-plugin",
+  crossVersion           := CrossVersion.full, // because compiler api is not binary compatible
+  libraryDependencies    += "org.scala-lang" % "scala-compiler" % scalaVersion.value,
+  OsgiKeys.exportPackage := Seq(s"scala.tools.escape;version=${version.value}")
+) settings (commonSettings : _*)
+
+val pluginJar = packageTask in (plugin, Compile)
+
+// TODO: the library project's test are really plugin tests, but we first need that jar
+lazy val library = project settings (scalaModuleOsgiSettings: _*) settings (MimaPlugin.mimaDefaultSettings: _*) settings (
+  name                       := "scala-escape-library",
+  MimaKeys.previousArtifact  := Some(organization.value % s"${name.value}_2.11.0-RC1" % "1.0.0"),
+  scalacOptions       ++= Seq(
+    // add the plugin to the compiler
+    s"-Xplugin:${pluginJar.value.getAbsolutePath}",
+    // enable the plugin
+    //"-P:escape:enable",
+    // add plugin timestamp to compiler options to trigger recompile of
+    // the library after editing the plugin. (Otherwise a 'clean' is needed.)
+    s"-Jdummy=${pluginJar.value.lastModified}"),
+  libraryDependencies ++= Seq(
+    "org.scala-lang" % "scala-compiler"  % scalaVersion.value % "test",
+    "junit"          % "junit"           % "4.11" % "test",
+    "com.novocode"   % "junit-interface" % "0.10" % "test"),
+  testOptions          += Tests.Argument(
+    TestFrameworks.JUnit,
+    s"-Dscala-escape-plugin.jar=${pluginJar.value.getAbsolutePath}"
+  ),
+  // run mima during tests
+  /*test in Test := {
+    MimaKeys.reportBinaryIssues.value
+    (test in Test).value
+  },*/
+  OsgiKeys.exportPackage := Seq(s"scala.util.escape;version=${version.value}")
+) settings (commonSettings : _*)

library/src/main/scala/scala/util/escape/safe.scala

@@ -0,0 +1,7 @@
+package scala.util.escape
+
+import scala.annotation.{ Annotation, StaticAnnotation, TypeConstraint }
+
+class safe(xs: Any*) extends StaticAnnotation with TypeConstraint
+
+case object %

library/src/test/scala/scala/tools/escape/CompilerTesting.scala

@@ -0,0 +1,49 @@
+package scala.tools.escape
+
+import org.junit.Test
+
+class CompilerTesting {
+  private def pluginJar: String = {
+    val f = sys.props("scala-escape-plugin.jar")
+    assert(new java.io.File(f).exists, f)
+    f
+  }
+  def loadPlugin = s"-Xplugin:${pluginJar}"
+
+  // note: `code` should have a | margin
+  def escErrorMessages(msg: String, code: String) =
+    errorMessages(msg, loadPlugin)(s"import scala.util.escape._\nobject Test {\ndef trycatch1: Unit = {\n${code.stripMargin}\n}\n}")
+
+  def expectEscErrorOutput(msg: String, code: String) = {
+    val errors = escErrorMessages(msg, code)
+    assert((errors mkString "\n") == msg, errors mkString "\n")
+  }
+
+  def expectEscError(msg: String, code: String) = {
+    val errors = escErrorMessages(msg, code)
+    assert(errors exists (_ contains msg), errors mkString "\n")
+  }
+
+  def expectEscErrors(msgCount: Int, msg: String, code: String) = {
+    val errors = escErrorMessages(msg, code)
+    val errorCount = errors.filter(_ contains msg).length
+    assert(errorCount == msgCount, s"$errorCount occurrences of \'$msg\' found -- expected $msgCount in:\n${errors mkString "\n"}")
+  }
+
+  // TODO: move to scala.tools.reflect.ToolboxFactory
+  def errorMessages(errorSnippet: String, compileOptions: String)(code: String): List[String] = {
+    import scala.tools.reflect._
+    val m = scala.reflect.runtime.currentMirror
+    val tb = m.mkToolBox(options = compileOptions) //: ToolBox[m.universe.type]
+    val fe = tb.frontEnd
+
+    try {
+      tb.eval(tb.parse(code))
+      Nil
+    } catch {
+      case _: ToolBoxError =>
+        import fe._
+        infos.toList collect { case Info(_, msg, ERROR) => msg }
+    }
+  }
+}

library/src/test/scala/scala/tools/escape/TestSuite.scala

@@ -0,0 +1,135 @@
+package scala.tools.escape
+
+import org.junit.Test
+import org.junit.Assert.assertEquals
+
+import scala.annotation._
+import scala.collection.Seq
+import scala.collection.generic.CanBuildFrom
+import scala.language.{ implicitConversions, higherKinds }
+import scala.util.escape._
+import scala.util.control.Exception
+
+
+class Basic extends CompilerTesting {
+  @Test def test10 = {
+    val x = 100
+    val y = 99
+
+    def f(a:Int): Int @safe(x) = a
+
+    def g1(a:Int): Int @safe(x) = f(a)
+
+    def g(a:Int): Int @safe(x) = a
+
+    def h(a: Int): Int @safe(x) = g(f(a))
+  }
+
+  @Test def test20 = expectEscErrorOutput(
+    "value x not safe (not declared as such by return type of f = (a: Int)Int!\n"+
+    "couldn't prove that object returned from f(a) does not point to Set(value x)",
+  """
+    val x = 100
+    val y = 99
+
+    def f(a:Int): Int = a
+    def g(a:Int): Int @safe(x) = f(a) // not safe
+  """)
+
+}
+
+class TryCatch extends CompilerTesting {
+
+  @Test def trycatch1: Unit = { () =>
+
+    def trycatch(f: (Exception => Nothing) => Unit @safe(%)): Unit = ???
+
+    trycatch { raise =>
+      raise(new Exception)
+    }
+
+  }
+
+  @Test def trycatch2: Unit = { () =>
+
+    def trycatch(f: (Exception => Nothing) => Unit @safe(%)): Unit = ???
+
+    def safeMethod(f: () => Unit): Unit @ safe(f) = ???
+
+    trycatch { raise =>
+      safeMethod { () =>
+        raise(new Exception)  // ok
+        ()
+      }
+      ()
+    }
+
+  }
+
+  @Test def trycatch3: Unit = { () =>
+
+    def trycatch(f: (Exception => Nothing) => Int @safe(%)): Int = ???
+
+    def safeMethod(f: () => Int): Int @ safe(f) = ???
+
+    trycatch { raise =>
+
+      def inner(a:Int): Int @safe(raise) = a
+
+      safeMethod { () =>
+        raise(new Exception)  // ok
+        inner(7)
+      }
+
+      9
+    }
+
+  }
+
+
+
+  @Test def trycatch4 = expectEscErrorOutput(
+    "value raise not safe (free in lambda)!","""
+
+    def trycatch(f: (Exception => Nothing) => Int @safe(%)): Int = ???
+
+    def safeMethod(f: () => Int): Int @ safe(f) = ???
+    def unsafeMethod(f: () => Int): Int = ???
+
+    trycatch { raise =>
+
+      safeMethod { () =>
+        raise(new Exception)  // ok
+        7
+      }
+
+      unsafeMethod { () =>
+        raise(new Exception)  // not ok
+        7
+      }
+      7
+    }
+  """)
+
+  @Test def trycatch5 = expectEscErrorOutput(
+    "couldn't prove that object returned from inner(7) does not point to Set(value raise)","""
+
+    def trycatch(f: (Exception => Nothing) => Int @safe(%)): Int = ???
+
+    def safeMethod(f: () => Int): Int @ safe(f) = ???
+
+    trycatch { raise =>
+
+      def inner(a:Int): Int = a
+
+      safeMethod { () =>
+        raise(new Exception)  // ok
+        inner(7) // not ok        
+      }
+
+      7
+    }
+  """)
+
+
+}