Package net.algart.arrays

Class AbstractIterativeArrayProcessor<T>

java.lang.Object

net.algart.arrays.AbstractIterativeArrayProcessor<T>

All Implemented Interfaces:

ArrayProcessor, IterativeArrayProcessor<T>

Direct Known Subclasses:

ErodingSkeleton, IterativeErosion, IterativeOpening, OctupleThinningSkeleton2D, Quadruple3x5ThinningSkeleton2D, StrongQuadruple3x5ThinningSkeleton2D, WeakOctupleThinningSkeleton2D

public abstract class AbstractIterativeArrayProcessor<T>
extends Object
implements IterativeArrayProcessor<T>

A skeletal implementation of the IterativeArrayProcessor interface. Usually, you need to extend this class to implement that interface.

All non-abstract methods are completely implemented here and usually should not be overridden in subclasses.

Author:

Daniel Alievsky

Field Summary

Fields

Modifier and Type	Field	Description
protected final ArrayContext	context	Current execution context.
protected final MemoryModel	memoryModel	The memory model used by this instance for all operations.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractIterativeArrayProcessor(ArrayContext context)	Creates an instance of this class with the given context.

Method Summary

Modifier and Type	Method	Description
IterativeArrayProcessor<T>	chain(IterativeArrayProcessor<T> followingProcessor, double weight)	Returns new object, implementing this interface, equivalent to the chain of this algorithm and followingProcessor algorithm, executed after this.
ArrayContext	context()	Returns the current context used by this instance for all operations.
abstract boolean	done()	Returns true if and only if the algorithm was successfully finished and there is no sense to perform further iterations.
abstract long	estimatedNumberOfIterations()	Estimates the number of iterations, that should be performed from this moment to finish the algorithm.
abstract void	freeResources(ArrayContext context)	If there are some resources, allocated by this object, which are not controlled by Java garbage collectors — files, streams, sockets, locks, etc. — this method tries to release them (for example, to close any files).
IterativeArrayProcessor<T>	limitIterations(long maxNumberOfIterations)	Returns new object, implementing this interface, equivalent to this algorithm with the only difference that the number of performed iterations does not exceed the specified argument.
static ArrayContext	part(ArrayContext context, double fromPart, double toPart)	This method returns context == null ? null : context.part(fromPart, toPart)).
abstract void	performIteration(ArrayContext context)	Performs the next iteration of the iterative algorithm.
T	process()	Performs a loop of calls of performIteration method, while IterativeArrayProcessor.done() method returns false.
abstract T	result()	Returns the result of the previous iteration.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

context

protected final ArrayContext context

Current execution context. It is returned by context() method.

memoryModel

protected final MemoryModel memoryModel

The memory model used by this instance for all operations. Equal to context.getMemoryModel() if context!=null, in other case equal to SimpleMemoryModel.getInstance().

Constructor Details

AbstractIterativeArrayProcessor

protected AbstractIterativeArrayProcessor(ArrayContext context)

Creates an instance of this class with the given context.

Parameters:

context - the context used by this instance for all operations (will be saved in context field).

Method Details

performIteration

public abstract void performIteration(ArrayContext context)

Description copied from interface: IterativeArrayProcessor

Performs the next iteration of the iterative algorithm. If the algorithm is IterativeArrayProcessor.done(), the results are unspecified: please never call this method if IterativeArrayProcessor.done() returns true.

You usually don't need to call this method: please call IterativeArrayProcessor.process() instead. If you need to perform only one or n iterations, you may use limitIterations(n) call.

Warning: this method should ignore the current execution context of this object. Instead, this method should use the context of execution specified by context argument. This method is called by IterativeArrayProcessor.process() method with the argument, describing a subtrask of the full algorithm. The context argument may be null: this method should work properly in this case (ignore the context).

This method must be implemented while creating a new iterative array-processing algorithm.

Specified by:

performIteration in interface IterativeArrayProcessor<T>

Parameters:

context - the context used by this instance for all operations; may be null.

done

public abstract boolean done()

Description copied from interface: IterativeArrayProcessor

Returns true if and only if the algorithm was successfully finished and there is no sense to perform further iterations.

This method usually does not perform actual calculations and works very quickly (just returns and internal flag). However, this condition is not strict.

You usually don't need to call this method: it is automatically called by IterativeArrayProcessor.process() method.

This method must be implemented while creating a new iterative array-processing algorithm.

Specified by:

done in interface IterativeArrayProcessor<T>

Returns:

true if and only if the algorithm was successfully finished.

estimatedNumberOfIterations

public abstract long estimatedNumberOfIterations()

Description copied from interface: IterativeArrayProcessor

Estimates the number of iterations, that should be performed from this moment to finish the algorithm. Returns 0 if it is impossible or too difficult to estimate this number: it means that the remaining number of iteration is unknown.

This method may require some time for its execution.

You usually don't need to call this method: it is automatically called from time to time by IterativeArrayProcessor.process() method. It is used for creating subcontexts, describing a part of the full task.

This method must be implemented while creating a new iterative array-processing algorithm.

Specified by:

estimatedNumberOfIterations in interface IterativeArrayProcessor<T>

Returns:

the estimated number of iterations, that should be performed from this moment to finish the algorithm.

result

public abstract T result()

Description copied from interface: IterativeArrayProcessor

Returns the result of the previous iteration. Usually it is UpdatableArray or Matrix<? extends UpdatableArray>. This method returns valid result even if no iterations were performed yet. If IterativeArrayProcessor.done() method returns true, the result of this method is the final result of iterative processing performed by this instance.

This method may return null. In this case, the concrete implementation of this interface should provide additional methods for returning calculation results.

This method does not perform actual calculations and works very quickly.

This method must be implemented while creating a new iterative array-processing algorithm.

Specified by:

result in interface IterativeArrayProcessor<T>

Returns:

the result of the previous iteration (may be null).

freeResources

public abstract void freeResources(ArrayContext context)

Description copied from interface: IterativeArrayProcessor

If there are some resources, allocated by this object, which are not controlled by Java garbage collectors — files, streams, sockets, locks, etc. — this method tries to release them (for example, to close any files). The object stays alive: if the resources will be necessary for following operations, they will be automatically re-acquired.

Usually, this method just calls Array.freeResources(context) and Matrix.freeResources(context) for all temporary arrays and matrices, allocated by this object for storing work data.

If IterativeArrayProcessor.result() method returns AlgART array or matrix (typical situation), this method calls Array.freeResources(context) / Matrix.freeResources(context) methods for this array / matrix.

This method may be used in situations when the instance of this object has long time life and will be reused in future.

This method must be implemented while creating a new iterative array-processing algorithm.

Specified by:

freeResources in interface IterativeArrayProcessor<T>

Parameters:

context - the context of execution; may be null, then it will be ignored.

context

public ArrayContext context()

Description copied from interface: ArrayProcessor

Returns the current context used by this instance for all operations. This method may return null; the classes, implementing this interface, should work in this situation as while using ArrayContext.DEFAULT context.

Specified by:

context in interface ArrayProcessor

Returns:

the current context used by this instance; may be null.

part

public static ArrayContext part(ArrayContext context,
 double fromPart,
 double toPart)

This method returns context == null ? null : context.part(fromPart, toPart)). This operation is needful very often while implementing performIteration(ArrayContext) method.

Parameters:

context - some array context.

fromPart - the estimated ready part, from 0.0 to 1.0, of the total algorithm at the start of the subtask: see ArrayContext.updateProgress method

toPart - the estimated ready part, from 0.0 to 1.0, of the total algorithm at the finish of the subtask: see ArrayContext.updateProgress method; must be not less than fromPart range.

Returns:

new context, describing the execution of the subtask of the current task.

Throws:

IllegalArgumentException - if fromPart or toPart is not in 0.0..1.0 range or if fromPart>toPart.

process

public T process()

Description copied from interface: IterativeArrayProcessor

Performs a loop of calls of performIteration method, while IterativeArrayProcessor.done() method returns false. It is the main method of this interface, used by application.

This method uses its current context to create an array context, that will be passed to IterativeArrayProcessor.performIteration(ArrayContext) method. The new context is made by ArrayContext.part(double, double) method, according to information returned by IterativeArrayProcessor.estimatedNumberOfIterations(). If the current context is null, this method pass null to IterativeArrayProcessor.performIteration(ArrayContext).

The maxNumberOfIterations argument allows to restrict the total number of calls of performIteration, that can be useful when the algorithm can work for very long time (thousands or millions iterations). If this argument is zero or positive, this method will perform, as a maximum, maxNumberOfIterations iterations (or less, if IterativeArrayProcessor.done() will return true before this). If it is zero, this method does nothing and immediately returns the IterativeArrayProcessor.result(). If it is negative, this argument is ignored.

Specified by:

process in interface IterativeArrayProcessor<T>

Returns:

the result of all calculations (the result of IterativeArrayProcessor.result() method after the last performed iteration).

limitIterations

public IterativeArrayProcessor<T> limitIterations(long maxNumberOfIterations)

Description copied from interface: IterativeArrayProcessor

Returns new object, implementing this interface, equivalent to this algorithm with the only difference that the number of performed iterations does not exceed the specified argument.

More precisely:

• the current context in the returned instance is equal to the current context of this instance.
• IterativeArrayProcessor.performIteration(ArrayContext context) in the returned instance always calls thisInstance.performIteration(context).
• IterativeArrayProcessor.done() in the returned instance is equivalent to count>=maxNumberOfIterations||thisInstance.IterativeArrayProcessor.done(), where count is the total number of performed calls of performIteration method.
• IterativeArrayProcessor.estimatedNumberOfIterations() in the returned instance always returns max(0,maxNumberOfIterations-count), where count is the total number of performed calls of performIteration method.
• IterativeArrayProcessor.result() in the returned instance always returns !thisInstance.IterativeArrayProcessor.result().
• freeResources(context) in the returned instance calls thisInstance.freeResources(context).

As a result, the basic IterativeArrayProcessor.process() method in the returned instance will perform, as a maximum, maxNumberOfIterations only. In particular, if maxNumberOfIterations==0, IterativeArrayProcessor.process() method does nothing and immediately returns IterativeArrayProcessor.result() object.

If maxNumberOfIterations<0, this method just returns the reference to this instance. In other words, negative maxNumberOfIterations means unlimited number of iterations.

Specified by:

limitIterations in interface IterativeArrayProcessor<T>

Parameters:

maxNumberOfIterations - the number of iterations, after which the IterativeArrayProcessor.done() method in the returned instance always returns true.

Returns:

new algorithm, equivalent to this algorithm with limited number of iterations.

chain

public IterativeArrayProcessor<T> chain(IterativeArrayProcessor<T> followingProcessor,
 double weight)

Description copied from interface: IterativeArrayProcessor

Returns new object, implementing this interface, equivalent to the chain of this algorithm and followingProcessor algorithm, executed after this. In other words, IterativeArrayProcessor.process() method of the returned instance performs iterations of this instance, while its IterativeArrayProcessor.done() method returns false, and then performs iterations of followingProcessor, while followingProcessor.IterativeArrayProcessor.done() method returns false.

More precisely:

• the current context in the returned instance is equal to the current context of this instance.
• IterativeArrayProcessor.performIteration(ArrayContext context) in the returned instance calls thisInstance.performIteration(context), if !thisInstance.IterativeArrayProcessor.done(), or calls followingProcessor.performIteration(context) in other case.
• IterativeArrayProcessor.done() in the returned instance is equivalent to thisInstance.IterativeArrayProcessor.done()&&followingProcessor.IterativeArrayProcessor.done().
• IterativeArrayProcessor.estimatedNumberOfIterations() in the returned instance calls n1=thisInstance.IterativeArrayProcessor.estimatedNumberOfIterations() and n2=followingProcessor.IterativeArrayProcessor.estimatedNumberOfIterations(), and returns n2 if thisInstance.IterativeArrayProcessor.done(), or, in other case, n1+Math.round(weight*n2), where weight is the 2nd argument if this method. (If n1==0 or n2==0, 0 is returned.) The necessity of the weight here is connected with the fact, that the followingProcessor may return illegal results, because this processor did not process the matrix yet.
• IterativeArrayProcessor.result() in the returned instance returns !thisInstance.IterativeArrayProcessor.done() ? thisInstance.IterativeArrayProcessor.result() : followingProcessor.IterativeArrayProcessor.result().
• freeResources(context) in the returned instance calls thisInstance.freeResources(c1) and followingProcessor.freeResources(c2), where c1 and c2 are parts of the passed context.

It is obvious that both instances of iterative algorithms, this and followingProcessor, must share the same processed data. In other words, followingProcessor (its IterativeArrayProcessor.performIteration(ArrayContext) and IterativeArrayProcessor.done() methods) must be able to "see" the results of execution of this processor. To provide this, the constructors (or generation methods) of both instances usually get a reference to the same updatable AlgART array or matrix, storing the intermediate calculation results.

Specified by:

chain in interface IterativeArrayProcessor<T>

Parameters:

followingProcessor - the next iterative algorithm, that should be performed after this will be done.

weight - the weight for estimated number of iterations of the next algorithm, used while first (this) one is not finished yet.

Returns:

new algorithm, equivalent to the chain of this algorithm and followingProcessor.