Revision: 14782
http://jikesrvm.svn.sourceforge.net/jikesrvm/?rev=14782&view=revAuthor: captain5050
Date: 2008-07-23 20:24:30 +0000 (Wed, 23 Jul 2008)
Log Message:
-----------
Add value to interruptible pragmas to allow them to carry documentation. Improve javadoc.
Modified Paths:
--------------
rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Interruptible.java
rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/LogicallyUninterruptible.java
rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Preemptible.java
rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Pure.java
rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Uninterruptible.java
rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/UninterruptibleNoWarn.java
rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Unpreemptible.java
Modified: rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Interruptible.java
===================================================================
--- rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Interruptible.java 2008-07-23 20:23:02 UTC (rev 14781)
+++ rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Interruptible.java 2008-07-23 20:24:30 UTC (rev 14782)
@@ -25,4 +25,9 @@
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Pragma
-public @interface Interruptible { }
+public @interface Interruptible {
+ /**
+ * @return Explanation of why code needs to be interruptible
+ */
+ String value() default "";
+}
Modified: rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/LogicallyUninterruptible.java
===================================================================
--- rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/LogicallyUninterruptible.java 2008-07-23 20:23:02 UTC (rev 14781)
+++ rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/LogicallyUninterruptible.java 2008-07-23 20:24:30 UTC (rev 14782)
@@ -19,30 +19,30 @@
import org.vmmagic.Pragma;
/**
- * A pragma that can be used to declare that a particular method is
- * logically uninterruptible even though it contains bytecodes that
- * are actually interruptible.
+ * A pragma that can be used to declare that a particular method is logically
+ * uninterruptible even though it contains bytecodes that are actually
+ * interruptible.
*
- * The effect of this pragma is to supress warning messages
- * about violations of uninterruptiblity when compiling a method
- * that throws this exception.
- * There are two cases in which using the pragma is justified.
+ * The effect of this pragma is to suppress warning messages about violations of
+ * uninterruptiblity when compiling a method that throws this exception. There
+ * are two cases in which using the pragma is justified.
* <ul>
- * <li> Uninterruptibility is ensured via some other mechansism.
- * For example, the method explicitly disables threadswitching
- * around the interruptible regions (VM.sysWrite on String).
- * Or the interruptible regions are not reachable when the VM is
- * running (various VM.sysWrite that check VM.runningVM).
- * <li> The interruptible regions represent an 'error' condition that will
- * never be executed unless the VM is already in the process of reporting
- * an error, for example RuntimeEntrypoints.raiseClassCastException.
+ * <li> Uninterruptibility is ensured via some other mechanism. For example, the
+ * method explicitly disables threadswitching around the interruptible regions
+ * (VM.sysWrite on String). Or the interruptible regions are not reachable when
+ * the VM is running (various VM.sysWrite that check VM.runningVM).
+ * <li> The interruptible regions represent an 'error' condition that will never
+ * be executed unless the VM is already in the process of reporting an error,
+ * for example RuntimeEntrypoints.raiseClassCastException.
* <ul>
- * Extreme care must be exercised when using this pragma since it supresses
- * the checking of uninterruptibility.
+ * Extreme care must be exercised when using this pragma since it suppresses the
+ * checking of uninterruptibility.
* <p>
- * Use of this pragma is being phased out since it lumps together two
- * possible special cases. Use either UnPreemptiblePragma or
- * UninterrpibleNoWarn instead. See also defect 1147447 for more context.
+ * Use of this pragma is being phased out since it lumps together two possible
+ * special cases. Use either {@link Unpreemptible} or
+ * {@link UninterruptibleNoWarn} instead.
+ * {@link <a href="
http://jira.codehaus.org/browse/RVM-115">RVM-115</a>} for more
+ * context.
* @deprecated
*/
@Retention(RetentionPolicy.RUNTIME)
Modified: rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Preemptible.java
===================================================================
--- rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Preemptible.java 2008-07-23 20:23:02 UTC (rev 14781)
+++ rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Preemptible.java 2008-07-23 20:24:30 UTC (rev 14782)
@@ -25,4 +25,9 @@
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
@Pragma
-public @interface Preemptible { }
+public @interface Preemptible {
+ /**
+ * @return Explanation of why code needs to be preemptible
+ */
+ String value() default "";
+}
Modified: rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Pure.java
===================================================================
--- rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Pure.java 2008-07-23 20:23:02 UTC (rev 14781)
+++ rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Pure.java 2008-07-23 20:24:30 UTC (rev 14782)
@@ -20,8 +20,10 @@
/**
* This pragma is used to indicate a method has no side effects. Use this pragma
- * with care as it will cause compile time invocation of the method it is placed
- * on.
+ * with care as it can cause compile time invocation of the method it is placed
+ * on. This pragma is used to imply weak purity of a method, and as such cannot
+ * remove calls to pure methods - as they may throw exceptions.
+ * {@link <a href="
http://jira.codehaus.org/browse/RVM-503">RVM-503</a>}.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
Modified: rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Uninterruptible.java
===================================================================
--- rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Uninterruptible.java 2008-07-23 20:23:02 UTC (rev 14781)
+++ rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Uninterruptible.java 2008-07-23 20:24:30 UTC (rev 14782)
@@ -40,4 +40,9 @@
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
@Pragma
-public @interface Uninterruptible { }
+public @interface Uninterruptible {
+ /**
+ * @return Explanation of why code needs to be uninterruptible
+ */
+ String value() default "";
+}
Modified: rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/UninterruptibleNoWarn.java
===================================================================
--- rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/UninterruptibleNoWarn.java 2008-07-23 20:23:02 UTC (rev 14781)
+++ rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/UninterruptibleNoWarn.java 2008-07-23 20:24:30 UTC (rev 14782)
@@ -19,7 +19,7 @@
import org.vmmagic.Pragma;
/**
- * A pragma that has the same direct effect as UninterruptiblePragma
+ * A pragma that has the same direct effect as {@link Uninterruptible}
* but also suppresses checking of uninterruptibility violations for
* the method. This should be used with care and is only justified when
* Uninterruptibility is ensured via some other mechansism.
@@ -31,4 +31,9 @@
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
@Pragma
-public @interface UninterruptibleNoWarn { }
+public @interface UninterruptibleNoWarn {
+ /**
+ * @return Explanation of why uninterruptible warnings are disabled
+ */
+ String value() default "";
+}
Modified: rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Unpreemptible.java
===================================================================
--- rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Unpreemptible.java 2008-07-23 20:23:02 UTC (rev 14781)
+++ rvmroot/trunk/common/vmmagic/src/org/vmmagic/pragma/Unpreemptible.java 2008-07-23 20:24:30 UTC (rev 14782)
@@ -32,4 +32,9 @@
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
@Pragma
-public @interface Unpreemptible { }
+public @interface Unpreemptible {
+ /**
+ * @return Explanation of why code needs to be unpreemptible
+ */
+ String value() default "";
+}
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/_______________________________________________
Jikesrvm-commits mailing list
Jikesrvm-commits@...
https://lists.sourceforge.net/lists/listinfo/jikesrvm-commits
