/* * Written by Doug Lea with assistance from members of JCP JSR-166 * Expert Group and released to the public domain, as explained at * http://creativecommons.org/publicdomain/zero/1.0/ */ package extra166y; import java.util.*; /** * Interfaces and utilities declaring per-element operations used * within parallel methods on aggregates. This class provides type * names for all operation signatures accepting zero, one or two * arguments, and returning zero or one results, for parameterized * types, as well as specializations to int, long, * and double. In keeping with normal Java evaluation rules * that promote, for example short to int, operation * names for these smaller types are absent. * *

Preliminary release note: Some of the declarations in this * class are likely to be moved elsewhere in the JDK libraries * upon actual release, and most likely will not all nested in the * same class. * *

The naming conventions are as follows: *

The name of the single method declared in each interface is * simply op (short for "operate"). * *
An Op (short for "operation") maps a single argument to * a result. Example: negating a value. * *
The names for scalar ops accepting and returning the same type * are prefaced by their type name. * *
A BinaryOp maps two arguments to a result. Example: * dividing two numbers * *
A Reducer is an associative binary op * accepting and returning values of the same type; where op(a, op(b, * c)) should have the same result as op(op(a, b), c). Example: * adding two numbers. * *
Scalar binary ops accepting and returning the same type * include their type name. * *
Mixed-type operators are named just by their argument type * names. * *
A Generator takes no arguments and returns a result. * Examples: random number generators, builders * *
A Procedure accepts an argument but doesn't return a * result. Example: printing a value. An Action is a * Procedure that takes no arguments. * *
A Predicate accepts a value and returns a boolean indicator * that the argument obeys some property. Example: testing if a number is even. * *
A BinaryPredicate accepts two values and returns a * boolean indicator that the arguments obeys some relation. Example: * testing if two numbers are relatively prime. * *
Scalar versions of {@link Comparator} have the same properties * as the Object version -- returning negative, zero, or positive * if the first argument is less, equal, or greater than the second. * *

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

result = op(a) or * result = op(a,b)
*	*	*	*	*	*	*	*
*	arg types *		result type *				*
*	a *	b *	`int` *	`long` *	`double` *	Object *	*
*	*	*	*	*	*	*	*
*	`int` *	<none> *	Ops.IntOp *	Ops.IntToLong *	Ops.IntToDouble *	Ops.IntToObject *	*
*	*	`int` *	Ops.BinaryIntOp *	Ops.IntAndIntToLong *	Ops.IntAndIntToDouble *	Ops.IntAndIntToObject *	*
*	*	`long` *	Ops.IntAndLongToInt *	Ops.IntAndLongToLong *	Ops.IntAndLongToDouble *	Ops.IntAndLongToObject *	*
*	*	`double` *	Ops.IntAndDoubleToInt *	Ops.IntAndDoubleToLong *	Ops.IntAndDoubleToDouble *	Ops.IntAndDoubleToObject *	*
*	*	Object *	Ops.IntAndObjectToInt *	Ops.IntAndObjectToLong *	Ops.IntAndObjectToDouble *	Ops.IntAndObjectToObject *	*
*	*	*	*	*	*	*	*
*	`long` *	<none> *	Ops.LongToInt *	Ops.LongOp *	Ops.LongToDouble *	Ops.LongToObject *	*
*	*	`int` *	Ops.LongAndIntToInt *	Ops.LongAndIntToLong *	Ops.LongAndIntToDouble *	Ops.LongAndIntToObject *	*
*	*	`long` *	Ops.LongAndLongToInt *	Ops.BinaryLongOp *	Ops.LongAndLongToDouble *	Ops.LongAndLongToObject *	*
*	*	`double` *	Ops.LongAndDoubleToInt *	Ops.LongAndDoubleToLong *	Ops.LongAndDoubleToDouble *	Ops.LongAndDoubleToObject *	*
*	*	Object *	Ops.LongAndObjectToInt *	Ops.LongAndObjectToLong *	Ops.LongAndObjectToDouble *	Ops.LongAndObjectToObject *	*
*	*	*	*	*	*	*	*
*	`double` *	<none> *	Ops.DoubleToInt *	Ops.DoubleToLong *	Ops.DoubleOp *	Ops.DoubleToObject *	*
*	*	`int` *	Ops.DoubleAndIntToInt *	Ops.DoubleAndIntToLong *	Ops.DoubleAndIntToDouble *	Ops.DoubleAndIntToObject *	*
*	*	`long` *	Ops.DoubleAndLongToInt *	Ops.DoubleAndLongToLong *	Ops.DoubleAndLongToDouble *	Ops.DoubleAndLongToObject *	*
*	*	`double` *	Ops.DoubleAndDoubleToInt *	Ops.DoubleAndDoubleToLong *	Ops.BinaryDoubleOp *	Ops.DoubleAndDoubleToObject *
*	*	Object *	Ops.DoubleAndObjectToInt *	Ops.DoubleAndObjectToLong *	Ops.DoubleAndObjectToDouble *	Ops.DoubleAndObjectToObject *	*
*	*	*	*	*	*	*	*
*	Object *	<none> *	Ops.ObjectToInt *	Ops.ObjectToLong *	Ops.ObjectToDouble *	Ops.Op *	*
*	*	`int` *	Ops.ObjectAndIntToInt *	Ops.ObjectAndIntToLong *	Ops.ObjectAndIntToDouble *	Ops.ObjectAndIntToObject *	*
*	*	`long` *	Ops.ObjectAndLongToInt *	Ops.ObjectAndLongToLong *	Ops.ObjectAndLongToDouble *	Ops.ObjectAndLongToObject *	*
*	*	`double` *	Ops.ObjectAndDoubleToInt *	Ops.ObjectAndDoubleToLong *	Ops.ObjectAndDoubleToDouble *	Ops.ObjectAndDoubleToObject *	*
*	*	Object *	Ops.ObjectAndObjectToInt *	Ops.ObjectAndObjectToLong *	Ops.ObjectAndObjectToDouble *	Ops.BinaryOp *	*
*	*	*	*	*	*	*

* *

In addition to stated signatures, implementations of these * interfaces must work safely in parallel. In general, this means * methods should operate only on their arguments, and should not rely * on ThreadLocals, unsafely published globals, or other unsafe * constructions. Additionally, they should not block waiting for * synchronization. * *