Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,25 @@ Other documentation in this repository and in the wiki explain in more detail ho

Other `test` and `spec` suites may also be appropriate depending on what functionality you are working on.

### Linking Java code to CRuby

When a method, class or field implements or ports a CRuby C function or macro, annotate it with `@CRuby` (`org.jruby.anno.CRuby`) rather than writing a `// MRI: rb_foo` comment:

```java
@CRuby(value = "match_begin", file = "re.c")
@JRubyMethod
public IRubyObject begin(ThreadContext context, IRubyObject index) {
```

`file` is optional. Repeat the annotation when one Java method covers several C functions.

Use `note` whenever the Java code is not a whole, one-to-one port of the C function:

* If it ports only part of the function, say which part: `note = "method redefinition check"`.
* If two Java methods carry the same annotation, give each a note that says which side it is, for example the pack and unpack halves of `pack_unpack_internal`. Without notes, reviewers have to assume two different ports of the same logic exist and check whether they disagree.

Explain what the code does in its Javadoc, not next to the annotation. When a port is long or subtle, explain it well. CRuby's own comments are often sparse, and JRuby's should do better.

## Testing

See [BUILDING.md](BUILDING.md) for more details.
Expand Down
49 changes: 15 additions & 34 deletions core/src/main/java/org/jruby/RubyMatchData.java
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@
import org.joni.Region;
import org.joni.exception.JOniException;
import org.joni.exception.ValueException;
import org.jruby.anno.CRuby;
import org.jruby.anno.JRubyClass;
import org.jruby.anno.JRubyMethod;
import org.jruby.api.Convert;
Expand Down Expand Up @@ -278,7 +279,7 @@ private void updateCharOffset() {

private static final int MATCH_BUSY = ObjectFlags.MATCH_BUSY;

// rb_match_busy
@CRuby(value = "rb_match_busy", file = "re.c")
public final void use() {
flags |= MATCH_BUSY;
}
Expand Down Expand Up @@ -467,9 +468,7 @@ public IRubyObject names(ThreadContext context, Block block) {
return getRegexp(context).names(context);
}

/** match_to_a
*
*/
@CRuby(value = "match_to_a", file = "re.c")
@JRubyMethod
@Override
public RubyArray to_a(ThreadContext context) {
Expand Down Expand Up @@ -503,9 +502,7 @@ public IRubyObject values_at(IRubyObject[] args) {
return values_at(getCurrentContext(), args);
}

/** match_captures
*
*/
@CRuby(value = "match_captures", file = "re.c")
@JRubyMethod
public IRubyObject captures(ThreadContext context) {
return match_array(context, 1);
Expand Down Expand Up @@ -559,7 +556,7 @@ public static int backrefNumber(ThreadContext context, Regex pattern, Region reg
return toInt(context, obj);
}

// MRI: namev_to_backref_number
@CRuby(value = "namev_to_backref_number", file = "re.c")
private int namevToBackrefNumber(ThreadContext context, IRubyObject name) {
int num = -1;

Expand All @@ -584,7 +581,7 @@ private int nameToBackrefError(ThreadContext context, String name) {
throw indexError(context, "undefined group name reference " + name);
}

// MRI: match_ary_subseq
@CRuby(value = "match_ary_subseq", file = "re.c")
private IRubyObject matchArySubseq(ThreadContext context, int beg, int len, RubyArray result) {
assert result != null;

Expand All @@ -607,7 +604,7 @@ private IRubyObject matchArySubseq(ThreadContext context, int beg, int len, Ruby
return result;
}

// MRI: match_ary_aref
@CRuby(value = "match_ary_aref", file = "re.c")
private IRubyObject matchAryAref(ThreadContext context, IRubyObject index, RubyArray result) {
int[] begLen = new int[2];
int numRegs = regs.getNumRegs();
Expand All @@ -629,19 +626,15 @@ private IRubyObject matchAryAref(ThreadContext context, IRubyObject index, RubyA
return matchArySubseq(context, begLen[0], begLen[1], result);
}

/** match_aref
*
*/
@CRuby(value = "match_aref", file = "re.c")
@JRubyMethod(name = "[]")
public IRubyObject op_aref(ThreadContext context, IRubyObject idx) {
check(context);
IRubyObject result = op_arefCommon(context, idx);
return result == null ? to_a(context).aref(context, idx) : result;
}

/** match_aref
*
*/
@CRuby(value = "match_aref", file = "re.c")
@JRubyMethod(name = "[]")
public IRubyObject op_aref(ThreadContext context, IRubyObject idx, IRubyObject rest) {
IRubyObject result;
Expand Down Expand Up @@ -670,18 +663,14 @@ public final IRubyObject at(ThreadContext context, final int nth) {
return RubyRegexp.nth_match(context, nth, this);
}

/** match_size
*
*/
@CRuby(value = "match_size", file = "re.c")
@JRubyMethod(name = {"size", "length"})
public IRubyObject size(ThreadContext context) {
check(context);
return regs == null ? RubyFixnum.one(context.runtime) : asFixnum(context, regs.getNumRegs());
}

/**
* MRI: match_begin
*/
@CRuby(value = "match_begin", file = "re.c")
@JRubyMethod
public IRubyObject begin(ThreadContext context, IRubyObject index) {
check(context);
Expand All @@ -697,9 +686,7 @@ public IRubyObject begin(ThreadContext context, IRubyObject index) {
return asFixnum(context, charOffsets.getBeg(i));
}

/** match_end
*
*/
@CRuby(value = "match_end", file = "re.c")
@JRubyMethod
public IRubyObject end(ThreadContext context, IRubyObject index) {
check(context);
Expand All @@ -724,9 +711,7 @@ public IRubyObject offset19(ThreadContext context, IRubyObject index) {
return offset(context, index);
}

/** match_offset
*
*/
@CRuby(value = "match_offset", file = "re.c")
@JRubyMethod(name = "offset")
public IRubyObject offset(ThreadContext context, IRubyObject index) {
check(context);
Expand Down Expand Up @@ -827,9 +812,7 @@ public IRubyObject post_match(ThreadContext context) {
context.nil : str.makeSharedString(context.runtime, end, str.getByteList().length() - end);
}

/** match_to_s
*
*/
@CRuby(value = "match_to_s", file = "re.c")
@JRubyMethod
@Override
public IRubyObject to_s(ThreadContext context) {
Expand All @@ -842,9 +825,7 @@ public IRubyObject to_s(ThreadContext context) {
public IRubyObject string() {
return string(getCurrentContext());
}
/** match_string
*
*/
@CRuby(value = "match_string", file = "re.c")
@JRubyMethod
public IRubyObject string(ThreadContext context) {
check(context);
Expand Down
81 changes: 81 additions & 0 deletions core/src/main/java/org/jruby/anno/CRuby.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
/***** BEGIN LICENSE BLOCK *****
* Version: EPL 2.0/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Eclipse Public
* License Version 2.0 (the "License"); you may not use this file
* except in compliance with the License. You may obtain a copy of
* the License at http://www.eclipse.org/legal/epl-v20.html
*
* Software distributed under the License is distributed on an "AS
* IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
* implied. See the License for the specific language governing
* rights and limitations under the License.
*
* Alternatively, the contents of this file may be used under the terms of
* either of the GNU General Public License Version 2 or later (the "GPL"),
* or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the EPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the EPL, the GPL or the LGPL.
***** END LICENSE BLOCK *****/

package org.jruby.anno;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
* Links a Java declaration to the CRuby C function or macro it implements or was ported from.
*
* <pre>
* &#64;CRuby("match_size")
* &#64;CRuby(value = "match_begin", file = "re.c")
* &#64;CRuby(value = "ary_reject_bang", file = "array.c")
* &#64;CRuby(value = "reject_bang_i", file = "array.c")
* &#64;CRuby(value = "rb_str_count", note = "first half")
* </pre>
*
* Use it in place of a {@code // MRI: rb_foo} comment or a Javadoc that only names the C function, so tools can
* audit the mapping and documentation can link to the C source. It has source retention to keep it out of
* lib/jruby.jar; switch to runtime retention if a tool needs to read it from a live JRuby.
*/
@Documented
@Retention(RetentionPolicy.SOURCE)
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.TYPE, ElementType.FIELD})
@Repeatable(CRuby.List.class)
public @interface CRuby {
/**
* The C function or macro, e.g. "match_integer_at".
*/
String value();

/**
* The C source file defining it, relative to the CRuby root, e.g. "re.c". Optional, mainly useful when the
* name is defined in more than one file.
*/
String file() default "";

/**
* Free text qualifying the link, e.g. "first half" or "loop body".
*/
String note() default "";

/**
* Container for repeated {@link CRuby} annotations; not used directly.
*/
@Documented
@Retention(RetentionPolicy.SOURCE)
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.TYPE, ElementType.FIELD})
@interface List {
CRuby[] value();
}
}
5 changes: 3 additions & 2 deletions core/src/main/java/org/jruby/ext/thread/Queue.java
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@
import org.jruby.RubyNumeric;
import org.jruby.RubyObject;
import org.jruby.RubyThread;
import org.jruby.anno.CRuby;
import org.jruby.anno.JRubyClass;
import org.jruby.anno.JRubyMethod;
import org.jruby.ast.util.ArgsUtil;
Expand Down Expand Up @@ -704,7 +705,7 @@ public IRubyObject pollInternal(long timeout, TimeUnit unit) throws InterruptedE
// masks the interrupt. Run interrupts that are not masked, then wait again.
// The other blocking queue tasks retry the same way.
@Override
// MRI: queue_do_pop, untimed wait loop
@CRuby(value = "queue_do_pop", file = "thread_sync.c", note = "untimed wait loop")
public IRubyObject run(ThreadContext context, Queue queue) {
while (true) {
try {
Expand Down Expand Up @@ -737,7 +738,7 @@ public BlockingPollTask(long timeoutNS) {

// Retries on interrupt like BLOCKING_TAKE_TASK, until the timeout.
@Override
// MRI: queue_do_pop, timed wait loop
@CRuby(value = "queue_do_pop", file = "thread_sync.c", note = "timed wait loop")
public IRubyObject run(ThreadContext context, Queue queue) {
long start = System.nanoTime();
while (true) {
Expand Down
5 changes: 3 additions & 2 deletions core/src/main/java/org/jruby/ext/thread/SizedQueue.java
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
import org.jruby.RubyHash;
import org.jruby.RubyNumeric;
import org.jruby.RubyThread;
import org.jruby.anno.CRuby;
import org.jruby.anno.JRubyClass;
import org.jruby.anno.JRubyMethod;
import org.jruby.ast.util.ArgsUtil;
Expand Down Expand Up @@ -268,7 +269,7 @@ public boolean offerInternal(ThreadContext context, IRubyObject e, long timeout,
private final RubyThread.Task<IRubyObject, IRubyObject> blockingPutTask = new RubyThread.Task<>() {
// Retries on interrupt like Queue.BLOCKING_TAKE_TASK.
@Override
// MRI: rb_szqueue_push, untimed wait loop
@CRuby(value = "rb_szqueue_push", file = "thread_sync.c", note = "untimed wait loop")
public IRubyObject run(ThreadContext context, IRubyObject value) {
while (true) {
try {
Expand All @@ -295,7 +296,7 @@ public BlockingOfferTask(long timeoutNS) {

// Retries on interrupt like Queue.BLOCKING_TAKE_TASK, until the timeout.
@Override
// MRI: rb_szqueue_push, timed wait loop
@CRuby(value = "rb_szqueue_push", file = "thread_sync.c", note = "timed wait loop")
public IRubyObject run(ThreadContext context, IRubyObject value) {
long start = System.nanoTime();
while (true) {
Expand Down
Loading