Changes between Version 5 and Version 6 of C++ API

Timestamp:

09/10/12 18:42:43 (12 years ago)

Author:

jorisborgdorff

Comment:

--

C++ API

@@ -99 +99 @@
 {{{init}}}, {{{finalize}}}, {{{will_stop}}}, {{{send}}}, and {{{receive}}} behave exactly as their C counterparts. Since scientific data is often vectors of doubles, there are two new convenience functions to send or receive only double vectors. Vectors are safer than arrays memory-wise and they do range-checking. If other vector methods are of interest to you, send us [[mailto:j.borgdorff@uva.nl|an email]]. Except for vectors, the data that is received must be freed by MUSCLE by calling {{{free_data}}} with the received pointer and the datatype of the received pointer.
 
-In addition to the datatypes that are available in the C API, the C++ API can also receive a {{{MUSCLE_COMPLEX}}} type. This will receive a {{{muscle::ComplexData}}} object, defined in the {{{muscle2/complex_data.hpp}}} header file. This ComplexData is used when the sender of a message sends different data than an array. In the enum {{{muscle_complex_t}}} all possible types are listed. For the moment only arrays and matrices are supported. Working with ComplexData goes as follows, for example with a two-dimensional double array
+=== Complex data ===
+
+In addition to the datatypes that are available in the C API, the C++ API can also receive a {{{MUSCLE_COMPLEX}}} type. This will receive a {{{muscle::ComplexData}}} object, defined in the {{{muscle2/complex_data.hpp}}} header file. This ComplexData is used when the sender of a message sends different data than an array. A Java sender might send a 2-D array of doubles, for instance. In the enum {{{muscle_complex_t}}} all possible types are listed. For the moment only arrays and matrices are supported. Working with ComplexData goes as follows, for example with a two-dimensional double array
 {{{
 #include <vector>
@@ -117 +119 @@
     }
     vector<int> dims = cdata->getDimensions();
+
+    // get the matrix as a vector
     double *data = (double *) cdata->getData();
+
+    // Do something with the data
     double result = 0;
     for (int x = 0; x < dims[0]; x++) {
         for (int y = 0; y < dims[1]; y++) {
+           // the matrix is indexed according to the different dimensions
            result += data[cdata->fidx(x,y)];
         }
     }
+    muscle::env::free_data(cdata, MUSCLE_COMPLEX);
     return result;
 }
 }}}
+The indices of the 2-D array are retrieved using the {{{index}}} or {{{fidx}}} function, where the latter is faster but does not do range or dimensionality checking. To send a ComplexData object it must first be constructed. The easiest way is to let ComplexData do the memory allocation and destruction, and getting the allocated memory from ComplexData to perform actual actions with.
+{{{
+vector<int> dims(2);
+// Set dimensions x and y
+dims[0] = 10; dims[1] = 14;
+ComplexData cdata(COMPLEX_DOUBLE_MATRIX_2D, &dims);
+double *data = (double *)cdata.getData();
+
+// Do something with the data
+double result = 0;
+for (int x = 0; x < dims[0]; x++) {
+    for (int y = 0; y < dims[1]; y++) {
+       // the matrix is indexed according to the different dimensions, using fidx
+       result += data[cdata.fidx(x,y)];
+    }
+}
+muscle::env::send("matrixOut", &cdata, cdata.length(), MUSCLE_COMPLEX);
+}}}