Skip to content
This repository was archived by the owner on Nov 8, 2022. It is now read-only.

scatter

Jump to bottom
Lindsey Kuper edited this page Feb 13, 2015 · 9 revisions

Description

Like combine, scatter allows us to produce a new ParallelArray out of an existing one by inspecting the existing ParallelArray object's elements, applying an elemental function to each of them, and returning a new ParallelArray containing the results of those function applications. Unlike combine, though, scatter allows us to specify, for a given source array location, the location in the result array that the result should appear.

Synopsis

myParallelArray.scatter(indices, defaultValue, conflictFunction, length)

Arguments

  • indices: an array of indices in the result array.
  • defaultValue: an optional argument indicating the value of elements not set by scatter. When not present, the default value is undefined.
  • conflictFunction: an optional argument, used to resolve index conflicts; details below.
  • length: an optional argument indicating the length of the result array. If absent, the length is the same as the length of the original ParallelArray.

Conflict Function

A conflict occurs when multiple elements are scattered to the same location. It results in a call to conflictFunction, which is an optional third argument to scatter. If conflictFunction is undefined, an exception is thrown.

function(a, b) { <body> }
  • a, b: the two values that conflict

The result of the conflict function is the elenent to place in result[indices[index]], where result is the result ParallelArray that scatter returns.

To ensure determinism, it is the programmer’s responsibility to provide a conflict function that is associative and commutative, since there is no guarantee of the order in which conflicts will be resolved. For instance, if three elements a, b, and c are scattered to the same location, then the final element written to that location could be conflictFunction(a, conflictFunction(b, c)), or it could be conflictFunction(conflictFunction(a, b), c) or conflictFunction(conflictFunction(a, c), b), and so on.

Inside the conflict function, the value of this will be the ParallelArray object on which scatter was invoked. For example, in the invocation of scatter above, this would refer to myParallelArray.

Returns

A freshly minted ParallelArray pa, where each element pa[i] is defined as:

  • pa[indices[i]] = this[i] when indices[i] is unique
  • pa[indices[i]] = conflictFunction(a, b) when elements a and b are scattered to the same location
  • defaultValue when i is not present in indices array

Examples

// an identity function; `identity` is a ParallelArray containing the
// elements [1, 2, 3, 4, 5]
var source = new ParallelArray([1,2,3,4,5]);
var indices = [0, 1, 2, 3, 4];
var identity = source.scatter(indices);

// here, the element at index 0 in `source` is mapped to index `4` in
// the result array.  `reorderedArray` is therefore a ParallelArray
// containing [2, 4, 5, 3, 1].
var reorderedArray = source.scatter([4,0,3,1,2]);

// if there is an index conflict, use the maximum of the conflicting
// elements, with 33 as a default value.
// `reorderedArrayWithConflictResolution` is therefore a ParallelArray
// containing [2, 33, 5, 3, 4].
var reorderedArrayWithConflictResolution =
  source.scatter([4,0,3,4,2],
                 33,
                 function max(a, b) { return a>b?a:b; });
     
// one way to create a histogram; `histogram` is a ParallelArray
// containing [0, 1, 3, 0, 2, 1].
var source = new ParallelArray([1,2,2,4,2,4,5]);
var ones = source.map(function one(v) { return 1; });
var histogram = ones.scatter(source,
                             0,
                             function plus(a,b) { return a+b; },
                             6);
Clone this wiki locally