appl.parallel.spmd
Interface SPMDClientInterface

All Known Subinterfaces:
AdvancedSPMDClientInterface
All Known Implementing Classes:
AdvancedSPMDClientController, SPMDClientController

public interface SPMDClientInterface

Using this interface the programmer can access the parallel functionality.

Author:
Dominik Appl

Method Summary
 void addBaseParameter(Object parameter, String parameterName)
          Base Parameters are Objects which are used during the execution of multiple SPMD-Tasks.
 void addBaseParameters(Object[] parameters, String[] parameterNames)
          Adds multiple Base-parameters at once.
 MultiDataObject addToMultiDataSplitControl(MultiGrid multiGrid, String name)
          This method is specialized on handling MultiGrids.
 MultiDataObject addToMultiDataSplitControl(Object[] splittableResources, String name)
          All resources of the array are submitted to split-control.
 void addToSplitControl(Object splittableResource, String name)
          The resource is submitted to splitControl.
 void mergeAllPartitions()
          Merges all the partitions from the server into the sources, from which the objects were loaded (which may be the Xulu-Client, but may also be a database or an other location if this feature is implemented).
 void mergeMultiData(MultiDataObject multidata)
          Merges all elements of the specified multidata object
 void mergeMultiData(MultiDataObject multidata, int idx)
          Merges the element at the specified index
 void mergePartition(int rootID)
          The counterpart of addToSplitControl(Object, String).
 void mergePartition(Object splittableResource)
          The counterpart of addToSplitControl(Object, String).
 Object[] runSPMDModelTask(SPMDTask task, Object... parameters)
          Run the given task on with the given parameters.
 void setBoxingMode(AbstractSplitMap.NeighborhoodBoxingMode boxingMode)
          Here you can set the boxing mode.
 void setNeighborhoodRange(int neighborhoodRange)
          Sets the neighborhood range.
 void setReferenceResource(Object splittableResource)
          All local bounds are calculated on server side using the reference resource.
 void updateNeighborhood(MultiDataObject multiDataObject, int index)
          Signals to all participating servers to update the neighborhood and waits until the update is finished.
 void updateNeighborhood(Object splittableResource)
          Signals to all participating servers to update the neighborhood and waits until the update is finished.
 

Method Detail

addBaseParameter

void addBaseParameter(Object parameter,
                      String parameterName)
Base Parameters are Objects which are used during the execution of multiple SPMD-Tasks. They are transfered to each of the participating computing resources but are not synchronized with the client and of course in no way splitted.

Notice: For efficient transport it is recommended that multiple parameters are transfered at once. To do this use the addBaseParameters(Object[], String[]) method.

Parameters:
parameter -
parameterName -
See Also:
SPMDServerController

addBaseParameters

void addBaseParameters(Object[] parameters,
                       String[] parameterNames)
Adds multiple Base-parameters at once. Notice that this is only for convenience and has no performance advantages over addBaseParameter(Object, String).

Parameters:
parameters - an array of parameters
parameterNames - an array of names. The indexes of parameters and parameter names must of course match

addToMultiDataSplitControl

MultiDataObject addToMultiDataSplitControl(Object[] splittableResources,
                                           String name)
All resources of the array are submitted to split-control. This means they are (virtually) split and send (virtually) to the participating computing units. The partitions can be requested on server side using the SPMDServerController.getMultiData(String) method. It is assumed, that all resources have the same Dimension. The same SplitMap and splitmap Position is used for all elements. used for every element.

Parameters:
splittableResources - the resource to be splitted
name - the name of the resource
Returns:
the multi-data object can be used for adding elements to the multi data
Throws:
UnsupportedOperationException - if splitHeight and splitWidth of the resouces does not match
See Also:
SPMDServerController

addToMultiDataSplitControl

MultiDataObject addToMultiDataSplitControl(MultiGrid multiGrid,
                                           String name)
This method is specialized on handling MultiGrids. In principle the addToMultiDataSplitControl(Object[], String) could be used, but using this method won't handle updates to the MultiGrid required for correct display in the XuluModellingPlatform.

The elements of the Multigrid are split and send to the participating computing units. The partitions can be requested on server side using the SPMDServerController.getMultiData(String) method. It is assumed, that all resources have the same Dimension. The same SplitMap and splitmap position is used for all elements.

Parameters:
name - the name of the resource
Returns:
the multi-data object can be used for adding elements to the multi data
Throws:
UnsupportedOperationException - if splitHeight and splitWidth of the resources does not match
See Also:
SPMDServerController

addToSplitControl

void addToSplitControl(Object splittableResource,
                       String name)
The resource is submitted to splitControl. This means it is virtually split and send virtually to the participating computing units. The partitions can be requested on server side using the SPMDServerController.getPartition(String) method.

What does "virtually" mean? Well what really happens is that the metadata is stored. When runSPMDModelTask is run next time, the metadata (and all base Parameters btw.) are Transfered to the servers.
The "real" splitting will happen implicit, i.e. the participating servers will request the correct partition.

Parameters:
splittableResource - the resource to be splitted
name - a name for the resource (you will be able to request the resource on server side using this name)
See Also:
SPMDServerController

mergeAllPartitions

void mergeAllPartitions()
Merges all the partitions from the server into the sources, from which the objects were loaded (which may be the Xulu-Client, but may also be a database or an other location if this feature is implemented).

See Also:
mergeAllPartitions(), addToSplitControl(Object, String)

mergeMultiData

void mergeMultiData(MultiDataObject multidata)
Merges all elements of the specified multidata object

Parameters:
multidata - the multidata to merge

mergeMultiData

void mergeMultiData(MultiDataObject multidata,
                    int idx)
Merges the element at the specified index

Parameters:
multidata - the multidata object containing the element to merge
idx - the position of the element to merge

mergePartition

void mergePartition(int rootID)
The counterpart of addToSplitControl(Object, String). Merges the partitions from the server into the sources, from which the objects were loaded (which will be the Xulu-Client in most cases, but may also be a database at an other location if this feature is implemented). Uses multithreading.

Parameters:
rootID - the ID of the source to be merged.
See Also:
mergeAllPartitions(), addToSplitControl(Object, String)

mergePartition

void mergePartition(Object splittableResource)
The counterpart of addToSplitControl(Object, String). Merges the partitions from the server into the sources, from which the objects were loaded (which will be the Xulu-Client in most cases, but may also be a database at an other location if this feature is implemented). Use mergeAllPartitions() to merge all partitions at once.

Parameters:
splittableResource - the resource to be merged. (must be an instance of SplittableResource
See Also:
mergeAllPartitions(), addToSplitControl(Object, String)

runSPMDModelTask

Object[] runSPMDModelTask(SPMDTask task,
                          Object... parameters)
                          throws Throwable
Run the given task on with the given parameters. The result is a Object array with results from all participating servers. The number of elements can therefore vary in different executions (using different numbers of servers)

Parameters:
task - the task to be submitted. There may be certain restrictions of the task to be submitted.
parameters -
Returns:
All results are combined in one array. Should a server not return a result, the parallel programmer is responsible for handling null values inside the array.
Throws:
Throwable - the Exceptions thrown on serverside!

setBoxingMode

void setBoxingMode(AbstractSplitMap.NeighborhoodBoxingMode boxingMode)
Here you can set the boxing mode. See AbstractSplitMap.NeighborhoodBoxingMode

Parameters:
boxingMode - the boxing mode

setNeighborhoodRange

void setNeighborhoodRange(int neighborhoodRange)
Sets the neighborhood range. From now on every splitting is done with the given range. In most cases it should be called before any resources are add to split control.

Parameters:
neighborhoodRange - the width of the neighborhood range (in cells)

setReferenceResource

void setReferenceResource(Object splittableResource)
All local bounds are calculated on server side using the reference resource. If splittable resources of different sizes or with different SplitMaps are used, it is possible to get the local bounds of an special resource using the SPMDServerController.getLocalCalculationBounds(appl.parallel.spmd.split.DataPartition) method of the SPMDServerController.

If no reference resource is set, than the first call to addToSplitControl(Object, String) will set the reference.

Parameters:
splittableResource - the new reference resource (must be an instance of SplittableResource)

updateNeighborhood

void updateNeighborhood(Object splittableResource)
Signals to all participating servers to update the neighborhood and waits until the update is finished.

Parameters:
splittableResource - (must be an instance of SplittableResource

updateNeighborhood

void updateNeighborhood(MultiDataObject multiDataObject,
                        int index)
Signals to all participating servers to update the neighborhood and waits until the update is finished.

Parameters:
multiDataObject - the MultiDataObject to be updated
index - the index of the partition to be updated