README.isc

Preparing a library
===================

APIs from an external library can't be linked directly with a motr instance.
A library is supposed to have a function named "void motr_lib_init(void)".
All APIs from a library shall confine to the following signature:

int comp(struct m0_buf *args, struct m0_buf *out,
         struct m0_isc_comp_private *comp_data, int *rc)

See isc_lib_demo.c for a usecase.

Loading a library
=================

Using a spiel command (@see "spiel/spiel.h" and "c0appz_isc.h") a library can
be loaded with any running motr instance. A helper function
"c0appz_isc_api_register" (c0appz_isc.h) takes a path of the library, which is
expected to be identical across all the nodes hosting a motr instance. Currently
a utility c0isc_reg takes the path as an input and loads the library with remote
motr instances.

On successful loading of the library the output looks like:

++++++++++++++++++++++++++++++
$ ./c0isc_reg $PWD/libdemo.so
c0isc_reg success
++++++++++++++++++++++++++++++

Demo computations
=================

Currently we demonstrate three simple computations. The utility c0isc_demo can
be used to invoke any of the computations supported. Following are the steps
to view the demo output.
1. make isc-clean
2. make isc-all

The second step builds a library libdemo.so

ping
----
This functionality pings all ISC services present in Motr configuration and
returns "Hello-World@<service-fid>" till it encounters a service that's down.

min / max
---------

This functionality reads a file (c0isc_data) co-located with the utility and
identifies the min or max depending upon the input option provided. On
successful completion it shows following output format:

+++++++++++++++++++++
$ ./c0isc_demo min
idx=0 val=1.100000
$ ./c0isc_demo max
idx=2 val=3.300000
+++++++++++++++++++++

The numbers in c0isc_data file are stored in text format delimited by space
(or newline): first integer specifies the number of elements followed by
the floating point elements themselves. For example:

+++++++++++++++++++
$ cat c0isc_data
3
1.1
2.2
3.3
+++++++++++++++++++

What's not present ?
====================

Data serialisation is necessary for communicating with remote service. Motr
serialises using gccxml and an internal utility gccxml2xcode. Incorporating
this utility in Motr rpm is currently scheduled and not part of current
Motr master. The demo includes a simplistic serialisation technique and
is not scalable as is.

Async communication with remote services is possible but the demo does not
include the same. For that kindly review cases from iscservice/ut/service_ut.c

Currently conducting an IO from server-side is not easily doable. It requires all
the operations that ioservice conducts needs to be  done. A simplified API
for server side IO is under progress. Hence result of the computation can not
be persisted as of now.