parallel/spmd/SPMDClientInterface.java

package appl.parallel.spmd;

import appl.parallel.ComputingResource;
import appl.parallel.spmd.split.AbstractSplitMap;
import appl.parallel.spmd.split.SplitMap;
import appl.parallel.spmd.split.SplittableResource;
import appl.parallel.spmd.split.AbstractSplitMap.NeighborhoodBoxingMode;
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	package appl.parallel.spmd;
2
3	import appl.parallel.ComputingResource;
4	import appl.parallel.spmd.split.AbstractSplitMap;
5	import appl.parallel.spmd.split.SplitMap;
6	import appl.parallel.spmd.split.SplittableResource;
7	import appl.parallel.spmd.split.AbstractSplitMap.NeighborhoodBoxingMode;
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	}