parallel/spmd/SPMDClientInterface.java

package appl.parallel.spmd;

import appl.parallel.ComputingResource;
import appl.parallel.spmd.split.AbstractSplitMap;
import appl.parallel.spmd.split.AbstractSplitMap.NeighborhoodBoxingMode;
import appl.parallel.spmd.split.SplitMap;
import appl.parallel.spmd.split.SplittableResource;
import edu.bonn.xulu.plugin.data.grid.MultiGrid;

/**
 * Using this interface the programmer can access the parallel functionality.
 *
 * @author Dominik Appl
 */
public interface SPMDClientInterface {

        /**
         * <code>Base Parameters</code> are Objects which are used during the
         * execution of multiple {@link SPMDTask SPMD-Tasks}. They are transfered
         * to each of the participating
         * {@link ComputingResource computing resources} but are not synchronized
         * with the client and of course in no way splitted. <br>
         * <br>
         * <b>Notice:</b> For efficient transport it is recommended that multiple
         * parameters are transfered at once. To do this use the
         * {@link #addBaseParameters(Object[], String[])} method.
         *
         * @param parameter
         * @param parameterName
         * @see SPMDServerController
         */
        public void addBaseParameter(Object parameter, String parameterName);

        /**
         * Adds multiple Base-parameters at once. Notice that this is only for
         * convenience and has no performance advantages over
         * {@link #addBaseParameter(Object, String)}.
         *
         * @param parameters
         *            an array of parameters
         * @param parameterNames
         *            an array of names. The indexes of parameters and parameter
         *            names must of course match
         */
        public void addBaseParameters(Object[] parameters, String[] parameterNames);

        /**
         * 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
         * {@link SPMDServerController#getMultiData(String)} method. It is assumed,
         * that all resources have the same Dimension. The same {@link SplitMap} and
         * splitmap Position is used for all elements. used for every element.
         *
         * @param splittableResources
         *            the resource to be splitted
         * @param name
         *            the name of the resource
         * @return the multi-data object can be used for adding elements to the
         *         multi data
         * @see SPMDServerController
         * @throws UnsupportedOperationException
         *             if splitHeight and splitWidth of the resouces does not match
         */
        public MultiDataObject addToMultiDataSplitControl(
                        Object splittableResources[], String name);

        /**
         * This method is specialized on handling MultiGrids. In principle the
         * {@link #addToMultiDataSplitControl(Object[], String)} could be used, but
         * using this method won't handle updates to the MultiGrid required for
         * correct display in the XuluModellingPlatform. <p/>
         * The elements of the Multigrid are split and send to the participating
         * computing units. The partitions can be requested on server side using the
         * {@link SPMDServerController#getMultiData(String)} method. It is assumed,
         * that all resources have the same Dimension. The same {@link SplitMap} and
         * splitmap position is used for all elements.
         * 
         * @param name
         *            the name of the resource
         * @return the multi-data object can be used for adding elements to the
         *         multi data
         * @see SPMDServerController
         * @throws UnsupportedOperationException
         *             if splitHeight and splitWidth of the resources does not match
         */
        public MultiDataObject addToMultiDataSplitControl(MultiGrid multiGrid,
                        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
         * {@link SPMDServerController#getPartition(String)} method. <br>
         * <br>
         * <i>What does "virtually" mean? </i>Well what really happens is that the
         * metadata is stored. When
         * {@link #runSPMDModelTask(SPMDTask, Object[]) runSPMDModelTask} is run
         * next time, the <b>metadata</b> (and all
         * {@link #addBaseParameter(Object, String)  base Parameters} btw.) are
         * Transfered to the servers. <br>
         * The "real" splitting will happen implicit, i.e. the participating servers
         * will request the correct partition.
         *
         * @param splittableResource
         *            the resource to be splitted
         * @param name
         *            a name for the resource (you will be able to request the
         *            resource on server side using this name)
         * @see SPMDServerController
         */
        public void addToSplitControl(Object splittableResource, String name);

        /**
         * 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 #mergeAllPartitions()
         * @see #addToSplitControl(Object, String)
         */
        public void mergeAllPartitions();

        /**
         * Merges all elements of the specified multidata object
         *
         * @param multidata
         *            the multidata to merge
         */
        public void mergeMultiData(MultiDataObject multidata);

        /**
         * Merges the element at the specified index
         *
         * @param multidata
         *            the multidata object containing the element to merge
         * @param idx
         *            the position of the element to merge
         */
        public void mergeMultiData(MultiDataObject multidata, int idx);

        /**
         * The counterpart of {@link #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.
         *
         * @param rootID
         *            the ID of the source to be merged.
         * @see #mergeAllPartitions()
         * @see #addToSplitControl(Object, String)
         */
        public void mergePartition(int rootID);

        /**
         * The counterpart of {@link #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 {@link #mergeAllPartitions()} to merge all partitions at once.
         *
         * @param splittableResource
         *            the resource to be merged. (must be an instance of
         *            {@link SplittableResource}
         * @see #mergeAllPartitions()
         * @see #addToSplitControl(Object, String)
         */
        public void mergePartition(Object splittableResource);

        /**
         * 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)
         *
         * @param task
         *            the task to be submitted. There may be certain restrictions of
         *            the task to be submitted.
         * @param parameters
         * @return All results are combined in one array. Should a server not return
         *         a result, the parallel programmer is responsible for handling
         *         <code>null</code> values inside the array.
         * @throws Throwable
         *             the Exceptions thrown on serverside!
         */
        public Object[] runSPMDModelTask(SPMDTask task, Object... parameters)
                        throws Throwable;

        /**
         * Here you can set the boxing mode. See {@link NeighborhoodBoxingMode}
         *
         * @param boxingMode
         *            the boxing mode
         */
        public void setBoxingMode(AbstractSplitMap.NeighborhoodBoxingMode boxingMode);

        /**
         * 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.
         *
         * @param neighborhoodRange
         *            the width of the neighborhood range (in cells)
         */
        public void setNeighborhoodRange(int neighborhoodRange);

        /**
         * All local bounds are calculated on server side using the reference
         * resource. If {@link SplittableResource splittable resources} of different
         * sizes or with different {@link SplitMap SplitMaps} are used, it is
         * possible to get the local bounds of an special resource using the
         * {@link SPMDServerController#getLocalCalculationBounds(appl.parallel.spmd.split.DataPartition)}
         * method of the SPMDServerController. <br>
         * <br>
         * If no reference resource is set, than the first call to
         * {@link #addToSplitControl(Object, String)} will set the reference.
         *
         * @param splittableResource
         *            the new reference resource (must be an instance of
         *            {@link SplittableResource})
         */
        public void setReferenceResource(Object splittableResource);

        /**
         * Signals to all participating servers to update the neighborhood and waits
         * until the update is finished.
         *
         * @param splittableResource
         *            (must be an instance of {@link SplittableResource}
         */
        public void updateNeighborhood(Object splittableResource);

        /**
         * Signals to all participating servers to update the neighborhood and waits
         * until the update is finished.
         *
         * @param multiDataObject
         *            the {@link MultiDataObject} to be updated
         * @param index
         *            the index of the partition to be updated
         */
        public void updateNeighborhood(MultiDataObject multiDataObject, int index);

}
1	mojays	2	package appl.parallel.spmd;
2
3			import appl.parallel.ComputingResource;
4			import appl.parallel.spmd.split.AbstractSplitMap;
5	mojays	114	import appl.parallel.spmd.split.AbstractSplitMap.NeighborhoodBoxingMode;
6	mojays	2	import appl.parallel.spmd.split.SplitMap;
7			import appl.parallel.spmd.split.SplittableResource;
8			import edu.bonn.xulu.plugin.data.grid.MultiGrid;
9
10			/**
11			* Using this interface the programmer can access the parallel functionality.
12			*
13			* @author Dominik Appl
14			*/
15			public interface SPMDClientInterface {
16
17			/**
18			* <code>Base Parameters</code> are Objects which are used during the
19			* execution of multiple {@link SPMDTask SPMD-Tasks}. They are transfered
20			* to each of the participating
21			* {@link ComputingResource computing resources} but are not synchronized
22			* with the client and of course in no way splitted. <br>
23			* <br>
24			* <b>Notice:</b> For efficient transport it is recommended that multiple
25			* parameters are transfered at once. To do this use the
26			* {@link #addBaseParameters(Object[], String[])} method.
27			*
28			* @param parameter
29			* @param parameterName
30			* @see SPMDServerController
31			*/
32			public void addBaseParameter(Object parameter, String parameterName);
33
34			/**
35			* Adds multiple Base-parameters at once. Notice that this is only for
36			* convenience and has no performance advantages over
37			* {@link #addBaseParameter(Object, String)}.
38			*
39			* @param parameters
40			* an array of parameters
41			* @param parameterNames
42			* an array of names. The indexes of parameters and parameter
43			* names must of course match
44			*/
45			public void addBaseParameters(Object[] parameters, String[] parameterNames);
46
47			/**
48			* All resources of the array are submitted to split-control. This means
49			* they are (virtually) split and send (virtually) to the participating
50			* computing units. The partitions can be requested on server side using the
51			* {@link SPMDServerController#getMultiData(String)} method. It is assumed,
52			* that all resources have the same Dimension. The same {@link SplitMap} and
53			* splitmap Position is used for all elements. used for every element.
54			*
55			* @param splittableResources
56			* the resource to be splitted
57			* @param name
58			* the name of the resource
59			* @return the multi-data object can be used for adding elements to the
60			* multi data
61			* @see SPMDServerController
62			* @throws UnsupportedOperationException
63			* if splitHeight and splitWidth of the resouces does not match
64			*/
65			public MultiDataObject addToMultiDataSplitControl(
66			Object splittableResources[], String name);
67
68			/**
69			* This method is specialized on handling MultiGrids. In principle the
70			* {@link #addToMultiDataSplitControl(Object[], String)} could be used, but
71			* using this method won't handle updates to the MultiGrid required for
72			* correct display in the XuluModellingPlatform. <p/>
73			* The elements of the Multigrid are split and send to the participating
74			* computing units. The partitions can be requested on server side using the
75			* {@link SPMDServerController#getMultiData(String)} method. It is assumed,
76			* that all resources have the same Dimension. The same {@link SplitMap} and
77			* splitmap position is used for all elements.
78			*
79			* @param name
80			* the name of the resource
81			* @return the multi-data object can be used for adding elements to the
82			* multi data
83			* @see SPMDServerController
84			* @throws UnsupportedOperationException
85			* if splitHeight and splitWidth of the resources does not match
86			*/
87			public MultiDataObject addToMultiDataSplitControl(MultiGrid multiGrid,
88			String name);
89
90			/**
91			* The resource is submitted to splitControl. This means it is virtually
92			* split and send virtually to the participating computing units. The
93			* partitions can be requested on server side using the
94			* {@link SPMDServerController#getPartition(String)} method. <br>
95			* <br>
96			* <i>What does "virtually" mean? </i>Well what really happens is that the
97			* metadata is stored. When
98			* {@link #runSPMDModelTask(SPMDTask, Object[]) runSPMDModelTask} is run
99			* next time, the <b>metadata</b> (and all
100			* {@link #addBaseParameter(Object, String) base Parameters} btw.) are
101			* Transfered to the servers. <br>
102			* The "real" splitting will happen implicit, i.e. the participating servers
103			* will request the correct partition.
104			*
105			* @param splittableResource
106			* the resource to be splitted
107			* @param name
108			* a name for the resource (you will be able to request the
109			* resource on server side using this name)
110			* @see SPMDServerController
111			*/
112			public void addToSplitControl(Object splittableResource, String name);
113
114			/**
115			* Merges all the partitions from the server into the sources, from which
116			* the objects were loaded (which may be the Xulu-Client, but may also be a
117			* database or an other location if this feature is implemented).
118			*
119			* @see #mergeAllPartitions()
120			* @see #addToSplitControl(Object, String)
121			*/
122			public void mergeAllPartitions();
123
124			/**
125			* Merges all elements of the specified multidata object
126			*
127			* @param multidata
128			* the multidata to merge
129			*/
130			public void mergeMultiData(MultiDataObject multidata);
131
132			/**
133			* Merges the element at the specified index
134			*
135			* @param multidata
136			* the multidata object containing the element to merge
137			* @param idx
138			* the position of the element to merge
139			*/
140			public void mergeMultiData(MultiDataObject multidata, int idx);
141
142			/**
143			* The counterpart of {@link #addToSplitControl(Object, String)}.
144			* Merges the partitions from the server into the sources, from which the
145			* objects were loaded (which will be the Xulu-Client in most cases, but may
146			* also be a database at an other location if this feature is implemented).
147			* Uses multithreading.
148			*
149			* @param rootID
150			* the ID of the source to be merged.
151			* @see #mergeAllPartitions()
152			* @see #addToSplitControl(Object, String)
153			*/
154			public void mergePartition(int rootID);
155
156			/**
157			* The counterpart of {@link #addToSplitControl(Object, String)}.
158			* Merges the partitions from the server into the sources, from which the
159			* objects were loaded (which will be the Xulu-Client in most cases, but may
160			* also be a database at an other location if this feature is implemented).
161			* Use {@link #mergeAllPartitions()} to merge all partitions at once.
162			*
163			* @param splittableResource
164			* the resource to be merged. (must be an instance of
165			* {@link SplittableResource}
166			* @see #mergeAllPartitions()
167			* @see #addToSplitControl(Object, String)
168			*/
169			public void mergePartition(Object splittableResource);
170
171			/**
172			* Run the given task on with the given parameters. The result is a Object
173			* array with results from all participating servers. The number of elements
174			* can therefore vary in different executions (using different numbers of
175			* servers)
176			*
177			* @param task
178			* the task to be submitted. There may be certain restrictions of
179			* the task to be submitted.
180			* @param parameters
181			* @return All results are combined in one array. Should a server not return
182			* a result, the parallel programmer is responsible for handling
183			* <code>null</code> values inside the array.
184			* @throws Throwable
185			* the Exceptions thrown on serverside!
186			*/
187			public Object[] runSPMDModelTask(SPMDTask task, Object... parameters)
188			throws Throwable;
189
190			/**
191			* Here you can set the boxing mode. See {@link NeighborhoodBoxingMode}
192			*
193			* @param boxingMode
194			* the boxing mode
195			*/
196			public void setBoxingMode(AbstractSplitMap.NeighborhoodBoxingMode boxingMode);
197
198			/**
199			* Sets the neighborhood range. From now on every splitting is done with the
200			* given range. In most cases it should be called before any resources are
201			* add to split control.
202			*
203			* @param neighborhoodRange
204			* the width of the neighborhood range (in cells)
205			*/
206			public void setNeighborhoodRange(int neighborhoodRange);
207
208			/**
209			* All local bounds are calculated on server side using the reference
210			* resource. If {@link SplittableResource splittable resources} of different
211			* sizes or with different {@link SplitMap SplitMaps} are used, it is
212			* possible to get the local bounds of an special resource using the
213			* {@link SPMDServerController#getLocalCalculationBounds(appl.parallel.spmd.split.DataPartition)}
214			* method of the SPMDServerController. <br>
215			* <br>
216			* If no reference resource is set, than the first call to
217			* {@link #addToSplitControl(Object, String)} will set the reference.
218			*
219			* @param splittableResource
220			* the new reference resource (must be an instance of
221			* {@link SplittableResource})
222			*/
223			public void setReferenceResource(Object splittableResource);
224
225			/**
226			* Signals to all participating servers to update the neighborhood and waits
227			* until the update is finished.
228			*
229			* @param splittableResource
230			* (must be an instance of {@link SplittableResource}
231			*/
232			public void updateNeighborhood(Object splittableResource);
233
234			/**
235			* Signals to all participating servers to update the neighborhood and waits
236			* until the update is finished.
237			*
238			* @param multiDataObject
239			* the {@link MultiDataObject} to be updated
240			* @param index
241			* the index of the partition to be updated
242			*/
243			public void updateNeighborhood(MultiDataObject multiDataObject, int index);
244
245			}