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

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.

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
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 >>


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.

• Related: mathematica.stackexchange.com/q/31433/12 Once I asked support about the DataStore type and they said " The DataStore type is part of an as-yet-undocumented C interface to pass event data from an asynchronous task. URLFetch uses this, as an example. But it only works asynchronously. And so far it is for internal use only." They also pointed to the example programs you reference. – Szabolcs Jan 14 '16 at 18:50
• @Szabolcs [...] so far it is for internal use only. Unfortunately this is a very bad news, I was counting on this features to move ahead. But ok, I respect the NDA. – Mark Messa Jan 14 '16 at 19:05
• @halirutan Do you agree with the comments above? Or do you consider that is still possible to use such asynchronous features? as we have talked before on this chat – Mark Messa Jan 14 '16 at 19:09
• I'm not sure what you mean, I didn't mention anything about NDAs. All I said was that I asked support about a certain thing related to these examples. I did not ask questions as specific as yours. They responded that these features are not publicly documented, but suggested that I can look at the provided example source code and learn from it. This was back in 2013. You can certainly try to figure out how to use these features, and asking about them here on StackExchange was a good idea. – Szabolcs Jan 14 '16 at 19:31
• @Szabolcs I didn't mention anything about NDAs There is a comment in your old question mentioning that maybe nobody could answer it because of NDAs. I though that such NDAs might still be a constraint today. – Mark Messa Jan 14 '16 at 19:39

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_] :=

1. 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.
2. The returned 1 is indeed the asyncObjID. I tested it and after starting several task the value is incremented.
3. 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 InternalCreateAsynchronousTask` and provide the loaded library function.