From ff1fe8b4ec64264171b419faff5fba4cf88b9a78 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Sun, 22 Jun 2014 20:12:57 +0200 Subject: Mentions memory management. --- doc/backends.txt | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 61 insertions(+), 5 deletions(-) (limited to 'doc/backends.txt') diff --git a/doc/backends.txt b/doc/backends.txt index 8bf353ff7..66d702f4e 100644 --- a/doc/backends.txt +++ b/doc/backends.txt @@ -265,7 +265,8 @@ Create a ``maths.c`` file with the following content: } Now you can run the following Unix like commands to first generate C sources -form the Nimrod code, then link it into a static binary:: +form the Nimrod code, then link them into a static binary along your main C +program:: $ nimrod c --noMain --noLinking --header:fib.h fib.nim $ gcc -o m -Inimcache -Ipath/to/nimrod/lib nimcache/*.c maths.c @@ -318,17 +319,72 @@ from the previous section): Compile the Nimrod code to JavaScript with ``nimrod js -o:fib.js fib.nim`` and open ``mhost.html`` in a browser. If the browser supports javascript, you -should see an alert box displaying the text ``Fib for 9 is 34``. +should see an alert box displaying the text ``Fib for 9 is 34``. As mentioned +earlier, JavaScript doesn't require an initialisation call to ``NimMain`` or +similar function and you can call the exported Nimrod proc directly. Memory management ================= +In the previous sections the ``NimMain()`` function reared its head. Since +JavaScript already provides automatic memory management, you can freely pass +objects between the two language without problems. In C and derivate languages +you need to be careful about what you do and how you share memory. The +previous examples only dealt with simple scalar values, but passing a Nimrod +string to C, or reading back a C string in Nimrod already requires you to be +aware of who controls what to avoid crashing. + + Strings and C strings --------------------- -Garbage collection, life of objects ------------------------------------ +The manual mentions that `Nimrod strings are implicitly convertible to +cstrings `_ which makes interaction usually +painless. Most C functions accepting a Nimrod string converted to a +``cstring`` will likely not need to keep this string around and by the time +they return the string won't be needed any more. However, for the rare cases +where a Nimrod string has to be preserved and made available to the C backend +as a ``cstring``, you will need to manually prevent the string data from being +freed with `GC_ref `_ and `GC_unref +`_. + +A similar thing happens with C code invoking Nimrod code which returns a +``cstring``. Consider the following proc: + +.. code-block:: nimrod + + proc gimme(): cstring {.exportc.} = + result = "Hey there C code! " & $random(100) + +Since Nimrod's garbage collector is not aware of the C code, once the +``gimme`` proc has finished it can reclaim the memory of the ``cstring``. +However, from a practical standpoint, the C code invoking the ``gimme`` +function directly will be able to use it since Nimrod's garbage collector has +not had a chance to run *yet*. This gives you enough time to make a copy for +the C side of the program, as calling any further Nimrod procs *might* trigger +garbage collection making the previously returned string garbage. Or maybe you +are `triggering yourself the collection `_. + + +Custom data types +----------------- + +Just like strings, custom data types that are to be shared between Nimrod and +the backend will need careful consideration of who controlls who. If you want +to hand a Nimrod reference to C code, you will need to use `GC_ref +`_ to mark the reference as used, so it does not get +freed. And for the C backend you will need to expose the `GC_unref +`_ proc to clean up this memory when it is not required +any more. + +Again, if you are wrapping a library which *mallocs* and *frees* data +structures, you need to expose the appropriate *free* function to Nimrod so +you can clean it up. And of course, once cleaned you should avoid accessing it +from Nimrod (or C for that matter). Typically C data structures have their own +``malloc_structure`` and ``free_structure`` specific functions, so wrapping +these for the Nimrod side should be enough. + Thread coordination -------------------- +=================== -- cgit 1.4.1-2-gfad0