Changes between Initial Version and Version 1 of C++ API

Timestamp:

09/07/12 15:09:59 (12 years ago)

Author:

jorisborgdorff

Comment:

--

C++ API

@@ +1 @@
+The C API of MUSCLE is a subset of the C++ API, the C API is again a subset of the Java API. Because the core of MUSCLE is written in Java, any C++ executable will communicate with Java code, but this is hidden in the API. In both cases, the include path is $MUSCLE_HOME/include
+
+== C API ==
+
+All muscle2 headers are installed in {{{$MUSCLE_HOME/include/muscle2}}}. The header for the C API is {{{muscle2/cmuscle.h}}}.
+
+The functions there are very limited, but they should be sufficient for most needs:
+{{{
+muscle_error_t MUSCLE_Init(int* argc, char*** argv);
+void MUSCLE_Finalize(void);
+
+const char* MUSCLE_Get_Kernel_Name(void);
+const char* MUSCLE_Get_Property(const char* name);
+int MUSCLE_Will_Stop(void);
+
+muscle_error_t MUSCLE_Send(const char *exit_name, void *array, size_t size, muscle_datatype_t type);
+void* MUSCLE_Receive(const char *entrance_name, void *array, size_t *size, muscle_datatype_t type);
+}}}
+The {{{MUSCLE_Init}}} function must be called before any of the other MUSCLE functions is used, and also before MPI_Init is called, if MPI is used. The usage is the same of MPI_Init: to initialize MUSCLE given the current arguments of main. After all MUSCLE calls have been made, MUSCLE_Finalize should be called. Usually:
+{{{
+int main(int argc, char *argv[])
+{
+    MUSCLE_Init(&argc, &argv);
+    ...
+    MUSCLE_Finalize();
+    return 0;
+}
+}}}
+After this, any code can be written. The MUSCLE_Get_Kernel_Name function gives the current kernel name. This must be freed after use. Similarly, MUSCLE_Get_Property gives a property as a string, which must be freed afterwards.
+
+The send and receive functions can transport several datatypes, which are enumerated in {{{muscle2/muscle_types.h}}}. For reference, it takes the following datatypes
+||={{{muscle_datatype_t}}}=||=C data type=||= Java data type =||=maximum size=||
+||{{{MUSCLE_DOUBLE}}}||{{{double *}}}||{{{double[]}}}||134e6 values ||
+||{{{MUSCLE_FLOAT}}}||{{{float *}}}||{{{float[]}}}||268e6 values||
+||{{{MUSCLE_INT32}}}||{{{int *}}}||{{{int[]}}}||268e6 values||
+||{{{MUSCLE_INT64}}}||{{{long *}}}||{{{long[]}}}||134e6 values||
+||{{{MUSCLE_STRING}}}||{{{char *}}}||{{{String}}}||64e3 characters||
+||{{{MUSCLE_RAW}}}||{{{unsigned char *}}}||{{{byte[]}}}||268e6 values||
+||{{{MUSCLE_COMPLEX}}}||{{{muscle::ComplexData *}}}||any other object||1 GiB||
+
+The type {{{MUSCLE_COMPLEX}}} is only available for C++ code.