public interface SpecialOp extends Op, Initializable, Threadable
OpEnvironment.run(java.lang.String, java.lang.Object...)
methods).
Special ops come in three major flavors: computer, function and inplace. In addition, hybrid ops union together computer, function and/or inplace in various combinations.
There are three arities currently implemented: NullaryOp,
UnaryOp and BinaryOp. These arities correspond to the number
of typed input parameters. Additional input parameters are allowed,
but not strongly typed at the interface level.
The following table summarizes the available kinds of special ops:
| Name | Summary | Stipulations | Output type | Arity | Class | Methods |
|---|---|---|---|---|---|---|
| computer | An op which computes a result from the given input I, storing the result into the specified preallocated output reference O. |
|
BOTH | 0 | NullaryComputerOp |
void compute(O) |
| 1 | UnaryComputerOp |
void compute(I, O) |
||||
| 2 | BinaryComputerOp |
void compute(I1, I2, O) |
||||
| function | An op which computes a result from the given input I, returning the result as a newly allocated output O. |
|
OUTPUT | 0 | NullaryFunctionOp |
O calculate() |
| 1 | UnaryFunctionOp |
O calculate(I) |
||||
| 2 | BinaryFunctionOp |
O calculate(I1, I2) |
||||
| inplace | An op which mutates the contents of its argument(s) in-place. | - | BOTH | 1 | UnaryInplaceOp |
void mutate(O) |
| 2 | BinaryInplace1Op |
void mutate1(O, I2) |
||||
| 2 | BinaryInplaceOp |
void mutate1(O, I2)
void mutate2(I1, O) |
||||
| hybrid CF | An op which is capable of behaving as either a computer or as a function, providing the API for both. | Same as computer and function respectively. | BOTH (optional) | 0 | NullaryHybridCF |
void compute(O)
O calculate() |
| 1 | UnaryHybridCF |
void compute(I, O)
O calculate(I) |
||||
| 2 | BinaryHybridCF |
O calculate(I1, I2)
void compute(I1, I2, O) |
||||
| hybrid CI | An op which is capable of behaving as either a computer or an inplace, providing the API for both. | Same as computer and inplace respectively. | BOTH (optional) | 1 | UnaryHybridCI |
void compute(I, O)
void mutate(O) |
| 2 | BinaryHybridCI1 |
void compute(I1, I2, O)
void mutate1(O, I2) |
||||
| 2 | BinaryHybridCI |
void compute(I1, I2, O)
void mutate1(O, I2)
void mutate2(I1, O) |
||||
| hybrid CFI | An op which is capable of behaving as either a computer, a function or an inplace, providing the API for all three. | Same as computer, function and inplace respectively. | BOTH (optional) | 1 | UnaryHybridCFI |
void compute(I, O)
O calculate(I)
void mutate(O) |
| 2 | BinaryHybridCFI1 |
void compute(I1, I2, O)
O calculate(I1, I2)
void mutate1(O, I2) |
||||
| 2 | BinaryHybridCFI |
void compute(I1, I2, O)
O calculate(I1, I2)
void mutate1(O, I2)
void mutate2(I1, O) |
It is allowed for ops to implement multiple special op types. For example, an
op may implement UnaryComputerOp as well as UnaryInplaceOp,
providing the option to compute the result in-place (saving memory) or into a
preallocated output reference (preserving the contents of the original input,
at the expense of memory).
| Modifier and Type | Interface and Description |
|---|---|
static class |
SpecialOp.Flavor
An enumeration of the primary kinds of special ops.
|
| Modifier and Type | Method and Description |
|---|---|
static List<OpCandidate> |
candidates(OpEnvironment ops,
String name,
Class<? extends Op> opType,
int arity,
SpecialOp.Flavor flavor) |
static List<OpCandidate> |
filterArity(List<OpCandidate> candidates,
int arity)
Extracts a sublist of op candidates with a particular arity.
|
int |
getArity()
Gets the op's number of special input parameters.
|
default SpecialOp |
getIndependentInstance()
Gets a reference to an instance of this object which can be used
simultaneously from a second thread while this instance is being used from
"its" thread.
|
static <S extends SpecialOp,O> |
op(OpEnvironment ops,
Class<? extends Op> opType,
Class<S> specialType,
Class<O> outType,
Object... args)
Gets the best
SpecialOp implementation for the given types and
arguments, populating its inputs. |
ops, setEnvironmentinitializeint getArity()
Note that this value may be larger than intuition might dictate in certain
scenarios, because UnaryOp extends NullaryOp, and
BinaryOp extends UnaryOp. This allows higher-order ops to
be treated as lower-order by holding the extra input parameters constant.
But it also means that e.g. a BinaryComputerOp which is locally
typed as UnaryComputerOp will report its arity as 2 rather than 1
as one might expect.
default SpecialOp getIndependentInstance()
ThreadableIt is expected that subclasses which override this method will narrow the return type appropriately. We do not enforce this at compile time via recursive generics due to their complexity: they introduce a host of typing difficulties.
getIndependentInstance in interface Threadablestatic <S extends SpecialOp,O> S op(OpEnvironment ops, Class<? extends Op> opType, Class<S> specialType, Class<O> outType, Object... args)
SpecialOp implementation for the given types and
arguments, populating its inputs.ops - The OpEnvironment to search for a matching op.opType - The Class of the operation. If multiple
SpecialOps share this type (e.g., the type is an interface
which multiple SpecialOps implement), then the best
SpecialOp implementation to use will be selected
automatically from the type and arguments.specialType - The SpecialOp type to which matches should be
restricted.outType - the type of the op's primary output, or null for any type.args - The operation's arguments.SpecialOp with populated inputs, ready to use.static List<OpCandidate> candidates(OpEnvironment ops, String name, Class<? extends Op> opType, int arity, SpecialOp.Flavor flavor)
static List<OpCandidate> filterArity(List<OpCandidate> candidates, int arity)
Copyright © 2014–2022 ImageJ. All rights reserved.