LibraryLink: Asynchronous Examples

Question

Inside the directory structure of LibraryLink there are several example files. Basically, they are divided in two types:

• Synchronous: demo.c, demo_error.c, demo_eval.c, demo_mathlink.c, demo_numerical.c, demo_shared.c, demo_string.c
• Asynchronous: async-examples-libmain.c, async-tasks-oneshot.c, async-tasks-repeating.c, async-tasks-timing.c, async-tasks-without-thread.c

The synchronous examples are well documented and relatively easy to use. However, the asynchronous are undocumented (as far as I know) and more difficult to use. So far, after some guesswork, the best I could figure it out is the following:

File Description

• async-examples-libmain.c: Initialization instructions (nothing to be executed within Mathematica).
• async-tasks-oneshot.c: Example of how to execute a task one single time and then close it.
• async-tasks-repeating.c: Example of how to execute a task continuously. This can be seen at the function IntBackgroundTask which has a while loop to keep the task alive.
• async-tasks-timing.c: Example of how to execute a task with time constraint. This can be seen at the function IntBackgroundTask which has a for loop limited by an iterator.
• async-tasks-without-thread.c: ????

File Structure
The main function of each one of the files is start_*_background_task and they are all very similar:

• The arguments are the same as of the synchronous ones (ie: always 3 arguments).
• The lines between mint asyncObjID; and asyncObjID = ioLibrary->createAsynchronousTaskWithThread(IntBackgroundTask, threadArg); sets and creates the asynchronous task.
• MArgument_setInteger returns a value to Mathematica, currently is returning only the value of asyncObjID. However, more calculations could be copy & paste before this line.

---

1st Issue
My guesswork is correct? Did I miss something?

2nd Issue
What the example file async-tasks-without-thread.c do?

3rd Issue
I'm trying to create a library for each one of the aforementioned files but some of them are not working. For example, when I execute the following:

<< CCompilerDriver`
demoFile = First@FileNames["async-tasks-oneshot.c", {$InstallationDirectory}, Infinity];
lib = CreateLibrary[{demoFile}, "mylib"];

I receive the following error message:

CreateLibrary::cmperr: Compile error: C:\Program Files\Wolfram Research\Mathematica\9.0\SystemFiles\Links\LibraryLink\LibraryResources\Source\async-tasks-oneshot.c(5) : fatal error C1083: Cannot open include file: 'async-examples.h': No such file or directory >>

The same happens with "async-tasks-repeating.c" and "async-tasks-without-thread.c".

What is going on? How to fix it?

4th Issue
If I just load the library (instead of creating it), I also get some behaviours not understood yet. For example:

fun = LibraryFunctionLoad["async-tasks-oneshot", "start_int_background_task", {Integer, Integer}, Integer];
fun[0, 0]

Out[2]:=1

I was expecting the output to be asyncObjID due the line MArgument_setInteger(Res, asyncObjID). Why this is not the case?

5th Issue
Moreover, after calling this fun[0,0], I can not evaluate anything else. For example:

1+1

It stays in the evaluation queue forever, but never returns an answer. Why this is happening? How to properly call the asynchronous function fun?

---

ps: Anticipating some comments, I'm trying to use this asynchronous feature in order to solve an issue with Low Level Networking Programming.

Answer 1

In Mathematica version 11.0 everything you need to know can be found in

SystemFiles/Links/LibraryLink/Examples.m

There, you find how you can call such a library function from within Mathematica. For example

CreateTimeDelayBackgroundTask[delayMillis_Integer, eventData_Integer, eventHandler_] := 
        Internal`CreateAsynchronousTask[startBackgroundTaskReturningInt, 
                {delayMillis, eventData}, eventHandler]

I don't comment on your first two issues, but for the answers for the rest are:

3. Seems to be no issue anymore. To solve it on an older version, just edit the example and remove the missing #include. I guess the came from some template code and did contain nothing or only forward declarations.

4. The returned 1 is indeed the asyncObjID. I tested it and after starting several task the value is incremented.

5. Well, if you call f[0,0] you say that you want a delay of 0 milliseconds. This might have been a problem. As can be seen in the example above, you need to use Internal`CreateAsynchronousTask and provide the loaded library function.

Finally, if you want a working example except for the ones the are provided by Mathematica, you can look at my answer that shows how to implement an asynchronous file watcher.