org.jruby.cext

Class NativeMethod

java.lang.Object

org.jruby.internal.runtime.methods.DynamicMethod

org.jruby.cext.NativeMethod

Direct Known Subclasses:

NativeMethod0, NativeMethod1, NativeMethod2, NativeMethod3, NativeProcMethod

public class NativeMethod
extends DynamicMethod

NativeMethod represents a method handle to a C extension function in JRuby, to provide entry points into C code. Native methods setup and tear down scope and context around a native method call and lock the GIL. Native methods restrict concurrency in C extensions to avoid threading issues in C code.

Nested Class Summary

Nested classes/interfaces inherited from class org.jruby.internal.runtime.methods.DynamicMethod

DynamicMethod.NativeCall

Field Summary

Fields

Modifier and Type	Field and Description
protected Arity	arity
protected long	function
private Native	nativeInstance

Fields inherited from class org.jruby.internal.runtime.methods.DynamicMethod

builtin, callConfig, handle, implementationClass, name, nativeCall, nativeCalls, notImplemented, protectedClass, serialNumber, visibility

Constructor Summary

Constructors

Constructor and Description
NativeMethod(RubyModule clazz, int arity, long function)

Method Summary

Modifier and Type	Method and Description
IRubyObject	call(ThreadContext context, IRubyObject recv, RubyModule clazz, java.lang.String name, IRubyObject[] args) A default implementation of n-arity, non-block 'call' method, which simply calls the n-arity, block-receiving version with the arg list and Block.NULL_BLOCK.
IRubyObject	call(ThreadContext context, IRubyObject recv, RubyModule clazz, java.lang.String name, IRubyObject[] args, Block block) The minimum 'call' method required for a dynamic method handle.
DynamicMethod	dup() Duplicate this method, returning DynamicMethod referencing the same code and with the same attributes.
Arity	getArity() Retrieve the arity of this method, used for reporting arity to Ruby code.
(package private) Native	getNativeInstance()
boolean	isNative() Returns true if this method is backed by native (i.e.
(package private) static void	post(ThreadContext context) Release the GIL and pop the call frame and scope.
(package private) static void	pre(ThreadContext context, IRubyObject self, RubyModule klazz, java.lang.String name) Pushes the method frame for execution of the native function.
(package private) static void	pre(ThreadContext context, IRubyObject self, RubyModule klazz, java.lang.String name, Block block) see pre(ThreadContext, IRubyObject, RubyModule, String)

Methods inherited from class org.jruby.internal.runtime.methods.DynamicMethod

calculateProtectedClass, call, call, call, call, call, call, call, call, getCallConfig, getHandle, getImplementationClass, getMethodData, getName, getNativeCall, getNativeCall, getProtectedClass, getRealMethod, getSerialNumber, getVisibility, handleBreak, handleRedo, handleReturn, init, isBuiltin, isCallableFrom, isNotImplemented, isUndefined, setCallConfig, setHandle, setImplementationClass, setIsBuiltin, setName, setNativeCall, setNativeCall, setNativeCall, setNotImplemented, setVisibility

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

arity

protected final Arity arity

function

protected final long function

nativeInstance

private final Native nativeInstance

Constructor Detail

NativeMethod

public NativeMethod(RubyModule clazz,
                    int arity,
                    long function)

Method Detail

dup

public final DynamicMethod dup()

Description copied from class: DynamicMethod

Duplicate this method, returning DynamicMethod referencing the same code and with the same attributes. It is not required that this method produce a new object if the semantics of the DynamicMethod subtype do not require such.

Specified by:

dup in class DynamicMethod

Returns:

An identical DynamicMethod object to the target.

getArity

public final Arity getArity()

Description copied from class: DynamicMethod

Retrieve the arity of this method, used for reporting arity to Ruby code. This arity may or may not reflect the actual specific or variable arities of the referenced method.

Overrides:

getArity in class DynamicMethod

Returns:

The arity of the method, as reported to Ruby consumers.

isNative

public final boolean isNative()

Description copied from class: DynamicMethod

Returns true if this method is backed by native (i.e. Java) code.

Overrides:

isNative in class DynamicMethod

Returns:

true If backed by Java code or JVM bytecode; false otherwise

pre

static void pre(ThreadContext context,
                IRubyObject self,
                RubyModule klazz,
                java.lang.String name)

Pushes the method frame for execution of the native function. Enforces use of a ManyVarsDynamicScope since we don't know what we will need in the function execution. Lastly, this acquires the GIL for native execution in the current Thread.

pre

static void pre(ThreadContext context,
                IRubyObject self,
                RubyModule klazz,
                java.lang.String name,
                Block block)

see pre(ThreadContext, IRubyObject, RubyModule, String)

post

static void post(ThreadContext context)

Release the GIL and pop the call frame and scope.

getNativeInstance

final Native getNativeInstance()

call

public IRubyObject call(ThreadContext context,
                        IRubyObject recv,
                        RubyModule clazz,
                        java.lang.String name,
                        IRubyObject[] args)

Description copied from class: DynamicMethod

A default implementation of n-arity, non-block 'call' method, which simply calls the n-arity, block-receiving version with the arg list and Block.NULL_BLOCK.

Overrides:

call in class DynamicMethod

Parameters:

context - The thread context for the currently executing thread

recv - The 'self' or 'receiver' object to use for this call

name - The incoming name used to invoke this method

Returns:

The result of the call

call

public IRubyObject call(ThreadContext context,
                        IRubyObject recv,
                        RubyModule clazz,
                        java.lang.String name,
                        IRubyObject[] args,
                        Block block)

Description copied from class: DynamicMethod

The minimum 'call' method required for a dynamic method handle. Subclasses must impleemnt this method, but may implement the other signatures to provide faster, non-boxing call paths. Typically subclasses will implement this method to check variable arity calls, then performing a specific-arity invocation to the appropriate method or performing variable-arity logic in-line.

Specified by:

call in class DynamicMethod

Parameters:

context - The thread context for the currently executing thread

recv - The 'self' or 'receiver' object to use for this call

name - The incoming name used to invoke this method

args - The argument list to this invocation

block - The block passed to this invocation

Returns:

The result of the call