Annotations for documenting methods and classes as "distributed object event

dispatch thread only", "blocking thread only" or "callable from any thread."

As the comment says, some day we'll look into enforcing these annotations with
some bytecode rewriting.


git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@4988 542714f4-19e9-0310-aa3c-eee0fc999fb1

src/java/com/threerings/presents/annotation/AnyThread.java

@@ -0,0 +1,39 @@
+//
+// $Id$
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2007 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.presents.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * An annotation indicating that a particular method in a class is safe to be called from any
+ * thread. This is not allowed on a class because it serves purely as documentation to demonstrate
+ * specific situations where methods are intended to be used by both the event dispatch and
+ * blocking threads which are generally uncommon.
+ */
+@Target(value=ElementType.METHOD)
+@Retention(value=RetentionPolicy.SOURCE)
+public @interface AnyThread
+{
+}

src/java/com/threerings/presents/annotation/BlockingThread.java

@@ -0,0 +1,41 @@
+//
+// $Id$
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2007 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.presents.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * An annotation indicating that a particular method or all methods in a class (that are not
+ * otherwise explicitly annotated) should only be called while on a servlet or invoker thread
+ * (threads which allow blocking).
+ *
+ * NOTE: These annotations are currently merely advisory, but someday we would like to use AspectJ
+ * or something like that to inject code that enforces these requirements on dev server builds.
+ */
+@Target(value={ ElementType.METHOD, ElementType.TYPE })
+@Retention(value=RetentionPolicy.SOURCE)
+public @interface BlockingThread
+{
+}

src/java/com/threerings/presents/annotation/EventThread.java

@@ -0,0 +1,41 @@
+//
+// $Id$
+//
+// Narya library - tools for developing networked games
+// Copyright (C) 2002-2007 Three Rings Design, Inc., All Rights Reserved
+// http://www.threerings.net/code/narya/
+//
+// This library is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as published
+// by the Free Software Foundation; either version 2.1 of the License, or
+// (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+package com.threerings.presents.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * An annotation indicating that a particular method or all methods in a class (that are not
+ * otherwise explicitly annotated) should only be called while on the distributed object event
+ * dispatch thread.
+ *
+ * NOTE: These annotations are currently merely advisory, but someday we would like to use AspectJ
+ * or something like that to inject code that enforces these requirements on dev server builds.
+ */
+@Target(value={ ElementType.METHOD, ElementType.TYPE })
+@Retention(value=RetentionPolicy.SOURCE)
+public @interface EventThread
+{
+}