Primitive
This abstraction represents the interface between Avail's Level One nybblecode interpreter and the underlying interfaces of the built-in objects, providing functionality that is (generally) inexpressible within Level One in terms of other Level One operations. A conforming Avail implementation must provide these primitives with equivalent semantics and names.
The subclasses must define attempt, which expects its arguments to be accessed via Interpreter.argument. Each subclass operates on its arguments to produce a side-effect and/or produce a result. The primitive's Flags indicate any special preparations that must be made before the invocation, such as reifying the Java stack.
Primitives may succeed or fail, or cause some other action like non-local control flow. This is handled via Interpreter.primitiveSuccess and Interpreter.primitiveFailure and similar methods. If a primitive fails, the statements in the containing function will be invoked, as though the primitive had never been attempted.
In addition, the Primitive subclasses collaborate with the L1Translator and L2Generator to produce appropriate L2Instructions and ultimately JVM bytecode instructions within a calling ExecutableChunk. Again, the Flags and some Primitive methods indicate general properties of the primitive, like whether it can be applied ahead of time (Flag.CanFold) to constant arguments, whether it could fail, given particular types of arguments, and what return type it guarantees to produce, given particular argument types.
The main hook for primitive-specific optimization is tryToGenerateSpecialPrimitiveInvocation. Because of the way the L2 translation makes use of L2SemanticValues, and L2SemanticPrimitiveInvocations in particular, a primitive can effectively examine the history of its arguments and compose or cancel a chain of actions in the L2 code. For example, a primitive that extracts an element of a tuple might notice that the tuple was created by a tuple-building primitive, and then choose to directly use one of the inputs to the tuple-building primitive, rather than decompose the tuple. If all such uses of the tuple disappear, the invocation of the tuple-building primitive can be elided entirely, since it has no side-effects. Arithmetic provides similarly rich opportunities for these high-level optimizations.
Author
Mark van Gulik
Parameters
The number of arguments the primitive expects. The value -1 is used by the special primitive P_PushConstant to indicate it may have any number of arguments. However, note that that primitive cannot be used explicitly in Avail code.
The flags that describe how the Interpreter and L2Generator should deal with this primitive.
Constructors
Types
These flags are used by the execution machinery and optimizer to indicate the potential mischief that the corresponding primitives may get into.
A helper class to assist with lazy loading of Primitives.
The success state of a primitive attempt.
Functions
Record that some number of nanoseconds were just expended checking the type of the value returned by this primitive.
Record that some number of nanoseconds were just expended running this primitive.
Attempt this primitive with the given Interpreter. The interpreter's argument list must be set up prior to this call. If the primitive fails, it should set the primitive failure code by calling Interpreter.primitiveFailure and returning its result from the primitive. Otherwise it should set the interpreter's primitive result by calling Interpreter.primitiveSuccess and then return its result from the primitive. For unusual primitives that replace the current continuation, Result.CONTINUATION_CHANGED is more appropriate, and the latestResult need not be set. For primitives that need to cause a context switch, Result.FIBER_SUSPENDED should be returned.
Attempt to generate a simplified, faster invocation of the given constant function, with the given argument restrictions. The arguments will be on the stack, the last-pushed one at stackp. If this code generation attempt is successful, code will be generated to invoke the given function, and if it completes without reification, to check the return result if it's not already guaranteed correct. Note that the call and the return type check can't be in separate instructions, since there's nowhere to store the unchecked return value to compare it against the expected type. We can't just clobber the expected type (that was pushed at the start of the call), since that would
Return a function type that restricts actual primitive blocks defined using that primitive. The actual block's argument types must be at least as specific as this function type's argument types, and the actual block's return type must be at least as general as this function type's return type. That's equivalent to the condition that the actual block's type is a subtype of this function type.
To simplify styling during bootstrapping, a method defined by the pragma mechanism can have its primitive declare a styler primitive to plug in as that method definition's styler.
Answer whether a raw function using this primitive can/should have nybblecode instructions.
Answer the fallibility of the primitive for a call site with the given argument types.
Write a JVM invocation of this primitive. This sets up the interpreter, calls Interpreter.beforeAttemptPrimitive, calls Primitive.attempt, calls Interpreter.afterAttemptPrimitive, and records statistics as needed. It also deals with primitive failures, suspensions, and reifications.
Test whether the specified Flag is set for this primitive.
Answer the type of the result that will be produced by a call site with the given argument types. Don't include semantic restrictions defined in the Avail code, but if convenient answer something stronger than the return type in the primitive's basic function type.
The primitive couldn't be folded out, and the primitive failed to produce specialized L2 instructions for itself. If the primitive is still known to be infallible (and does not affect the continuation stack) at this site, generate an L2_RUN_INFALLIBLE_PRIMITIVE for it and answer true, ensuring control flow will go to the appropriate CallSiteHelper exit point, and leave the translator NOT at a currentReachable() point.
The primitive couldn't be folded out, so see if alternative instructions can be generated for its invocation. If so, answer true, ensure control flow will go to the appropriate CallSiteHelper exit point, and leave the translator NOT at a currentReachable() point. If the alternative instructions could not be generated for this primitive, answer false, and generate nothing.
Generate suitable primitive failure code on the given L1InstructionWriter. Some primitives may have special requirements, but most (fallible) primitives follow the same pattern.
Properties
The number of arguments the primitive expects. The value -1 is used by the special primitive P_PushConstant to indicate it may have any number of arguments. However, note that that primitive cannot be used explicitly in Avail code.
A type to constrain the A_Type.writeType of the variable declaration within the primitive declaration of a block. The actual variable's inner type must be this or a supertype.
The Statistic for abandoning the stack due to a primitive attempt answering Result.CONTINUATION_CHANGED.
The Statistic for reification prior to invoking a primitive that does not have Flag.CanInline set.