Top Description Methods
org.python.core

pack-priv Interface FastCall

Known Direct Implementers
org.python.core.MethodDescriptor, org.python.core.PyMethodWrapper, org.python.core.PyJavaFunction
Imports
java.util.Arrays
Support direct calls from Java to the function represented by this object, potentially without constructing an argument array. Clients that know the number of arguments they provide are able to call call(...) with exactly that number. Callable objects that implement this interface may override signatures of call(...) that they implement most efficiently.

This is an efficiency mechanism similar to the "fast call" paths in CPython. It may provide a basis for efficient call sites for function and method calling when argument lists are simple.

Method Summary

Modifier and TypeMethod and Description
public Object

Returns:

result of the invocation
call(Object[]
all arguments given, positional then keyword
args, String[]
of keyword arguments or null
names)

Invoke the target object with standard arguments (Object[] and String[]), providing all the argument values from the caller and names for those given by keyword.

public default Object

Returns:

result of the invocation
call(Object[]
arguments given by position
args)

Call the object with arguments given by position only.

public default Object

Returns:

result of the invocation
call()

Call the object with arguments given by position only.

public default Object

Returns:

result of the invocation
call(Object
single argument (may be self)
a0)

Call the object with arguments given by position only.

public default Object

Returns:

result of the invocation
call(Object
zeroth argument (may be self)
a0, Object
next argument
a1)

Call the object with arguments given by position only.

public default Object

Returns:

result of the invocation
call(Object
zeroth argument (may be self)
a0, Object
next argument
a1, Object
next argument
a2)

Call the object with arguments given by position only.

public default Object

Returns:

result of the invocation
call(Object
zeroth argument (may be self)
a0, Object
next argument
a1, Object
next argument
a2, Object
next argument
a3)

Call the object with arguments given by position only.

public TypeError

Returns:

Python TypeError to throw
typeError(ArgumentError
previously thrown by this object
ae, Object[]
all arguments given, positional then keyword
args, String[]
of keyword arguments or null
names)

Translate an ArgumentError that resulted from a call to this FastCall object, and the arguments that were supplied in the call, to a Python TypeError.

public default TypeError

Returns:

Python TypeError to throw
typeError(ArgumentError
previously thrown by this object
ae, Object[]
all arguments given, positional then keyword
args)

As typeError(ArgumentError, Object[], String[]) when there were no arguments by keyword.

public default TypeError

Returns:

Python TypeError to throw
typeError(ArgumentError
previously thrown by this object
ae, Object[]
positional and keyword arguments
s, int
position of arguments in the array
p, int
number of positional and keyword arguments
n, String[]
of keyword arguments or null
names)

As typeError(ArgumentError, Object[], String[]) for vectorcall(Object[], int, int, String[]) arguments.

public default TypeError

Returns:

Python TypeError to throw
typeError(ArgumentError
previously thrown by this object
ae, Object[]
positional and keyword arguments
s, int
position of arguments in the array
p, int
number of positional arguments
n)

As typeError(ArgumentError, Object[], int, int, String[]) when there were no arguments by keyword.

public default Object

Returns:

the return from the call to the object
vectorcall(Object[]
positional and keyword arguments
s, int
position of arguments in the array
p, int
number of positional and keyword arguments
n, String[]
of keyword arguments or null
names)

Call this object with the vector call protocol.

public default Object

Returns:

the return from the call to the object
vectorcall(Object[]
positional and keyword arguments
s, int
position of arguments in the array
p, int
number of positional arguments
n)

Call this object with the vector call protocol, in the case where no arguments were given by keyword.

Method Detail

callback to summary
public Object call(Object[] args, String[] names) throws ArgumentError, Throwable

Invoke the target object with standard arguments (Object[] and String[]), providing all the argument values from the caller and names for those given by keyword. If no other methods are implemented, a call to any other interface method will land here with an array of the arguments.This is to provide implementations of __call__ with a default when no more optimal call is possible.

np = args.length - names.length arguments are given by position, and the keyword arguments are {names[i]:args[np+i]}.

Implementation Specification

An object that is a FastCall must support the standard call (and with the same result as the direct call). It must not call any other method in this interface, as that would risk creating a loop.

Implementation Note

The reason we do not name this method __call__ is because that may be called directly from Python, and an object should have the chance to choose amongst the optimised implementations specified by this interface, finally resorting to call(Object[], String[]) if necessary.

Parameters
args:Object[]

all arguments given, positional then keyword

names:String[]

of keyword arguments or null

Returns:Object

result of the invocation

Exceptions
ArgumentError:
if the wrong number of arguments is given, or keywords where not expected.
Throwable:
from the implementation
callback to summary
public default Object call(Object[] args) throws ArgumentError, Throwable

Call the object with arguments given by position only.

Implementation Specification

The default implementation calls call(Object[], String[]) with a null array of names.

Parameters
args:Object[]

arguments given by position

Returns:Object

result of the invocation

Exceptions
ArgumentError:
if the wrong number of arguments is given.
Throwable:
from the implementation
callback to summary
public default Object call() throws ArgumentError, Throwable

Call the object with arguments given by position only.

Implementation Specification

The default implementation calls call(Object[]) with an empty array.

Returns:Object

result of the invocation

Exceptions
ArgumentError:
if zero arguments is the wrong number.
Throwable:
from the implementation
callback to summary
public default Object call(Object a0) throws ArgumentError, Throwable

Call the object with arguments given by position only.

Implementation Specification

The default implementation calls call(Object[]) with an array the single argument.

Parameters
a0:Object

single argument (may be self)

Returns:Object

result of the invocation

Exceptions
ArgumentError:
if one argument is the wrong number.
Throwable:
from the implementation
callback to summary
public default Object call(Object a0, Object a1) throws ArgumentError, Throwable

Call the object with arguments given by position only.

Implementation Specification

The default implementation calls call(Object[]) with an array of the arguments.

Parameters
a0:Object

zeroth argument (may be self)

a1:Object

next argument

Returns:Object

result of the invocation

Exceptions
ArgumentError:
if two arguments is the wrong number.
Throwable:
from the implementation
callback to summary
public default Object call(Object a0, Object a1, Object a2) throws ArgumentError, Throwable

Call the object with arguments given by position only.

Implementation Specification

The default implementation calls call(Object[]) with an array of the arguments.

Parameters
a0:Object

zeroth argument (may be self)

a1:Object

next argument

a2:Object

next argument

Returns:Object

result of the invocation

Exceptions
ArgumentError:
if three arguments is the wrong number.
Throwable:
from the implementation
callback to summary
public default Object call(Object a0, Object a1, Object a2, Object a3) throws ArgumentError, Throwable

Call the object with arguments given by position only.

Implementation Specification

The default implementation calls call(Object[]) with an array of the arguments.

Parameters
a0:Object

zeroth argument (may be self)

a1:Object

next argument

a2:Object

next argument

a3:Object

next argument

Returns:Object

result of the invocation

Exceptions
ArgumentError:
if four arguments is the wrong number.
Throwable:
from the implementation
typeErrorback to summary
public TypeError typeError(ArgumentError ae, Object[] args, String[] names)

Translate an ArgumentError that resulted from a call to this FastCall object, and the arguments that were supplied in the call, to a Python TypeError.

Any of the optimised call(...), or vectorcall(...) methods in this interface may throw ArgumentError as a shorthand. (This is to keep code short, especially when it is a handle graph.) The caller should catch this close to the call and use this method to swap the ArgumentError for a Python TypeError.

Parameters
ae:ArgumentError

previously thrown by this object

args:Object[]

all arguments given, positional then keyword

names:String[]

of keyword arguments or null

Returns:TypeError

Python TypeError to throw

typeErrorback to summary
public default TypeError typeError(ArgumentError ae, Object[] args)

As typeError(ArgumentError, Object[], String[]) when there were no arguments by keyword.

Parameters
ae:ArgumentError

previously thrown by this object

args:Object[]

all arguments given, positional then keyword

Returns:TypeError

Python TypeError to throw

typeErrorback to summary
public default TypeError typeError(ArgumentError ae, Object[] s, int p, int n, String[] names)

As typeError(ArgumentError, Object[], String[]) for vectorcall(Object[], int, int, String[]) arguments.

Parameters
ae:ArgumentError

previously thrown by this object

s:Object[]

positional and keyword arguments

p:int

position of arguments in the array

n:int

number of positional and keyword arguments

names:String[]

of keyword arguments or null

Returns:TypeError

Python TypeError to throw

typeErrorback to summary
public default TypeError typeError(ArgumentError ae, Object[] s, int p, int n)

As typeError(ArgumentError, Object[], int, int, String[]) when there were no arguments by keyword.

Parameters
ae:ArgumentError

previously thrown by this object

s:Object[]

positional and keyword arguments

p:int

position of arguments in the array

n:int

number of positional arguments

Returns:TypeError

Python TypeError to throw

vectorcallback to summary
public default Object vectorcall(Object[] s, int p, int n, String[] names) throws ArgumentError, Throwable

Call this object with the vector call protocol. This supports CPython byte code generated according to the conventions in PEP-590.

The stack argument (which is often the interpreter stack) contains, at a given offset start, the count arguments of which the last len(kw) are given by keyword (and may therefore not be in the order expected by the called object).

Parameters
s:Object[]

positional and keyword arguments

p:int

position of arguments in the array

n:int

number of positional and keyword arguments

names:String[]

of keyword arguments or null

Returns:Object

the return from the call to the object

Exceptions
ArgumentError:
if the wrong number of arguments is given, or keywords where not expected.
Throwable:
for errors raised in the function
TypeError:
if target is not callable
vectorcallback to summary
public default Object vectorcall(Object[] s, int p, int n) throws ArgumentError, Throwable

Call this object with the vector call protocol, in the case where no arguments were given by keyword. This supports CPython byte code generated according to the conventions in PEP-590, but specialised for this case.

The stack argument (which is often the interpreter stack) contains, at a given offset start, the count arguments given by position.

Parameters
s:Object[]

positional and keyword arguments

p:int

position of arguments in the array

n:int

number of positional arguments

Returns:Object

the return from the call to the object

Exceptions
ArgumentError:
if the wrong number of arguments is given.
Throwable:
for errors raised in the function
TypeError:
if target is not callable