Predictable garbage collection with Lua

In one of my previous posts I talked about how you can make the Lua garbage collector (GC) more predictable in running time. This is a virtue that is highly valued in a GC used in games where you don’t have the luxury of going over you frame time. In that post I described a solution to the problem which works fine most of the time, leaving little space for garbage collection times that will hurt the framerate. However I ended that post with a promise to provide a better solution and in this post, I deliver.

The ideal situation would be to have the GC run for a specific amount of time. This way the game engine will be able to assign exact CPU time to the GC based on the situation. For example one strategy would be to give a constant amount of time to the GC per frame. Lets say 2ms every frame. Or it can be more clever and take into consideration other parameters, like the amount of time it took to do the actual frame. Is there enough time left for this frame? If there is, spend some for GC, if not, hold it for the next frame when things might not be too tight. Other parameters can be memory thresholds, memory warnings, etc.

All of the above depend on a GC that can be instructed to run for an exact amount of time. This kind of GC is what we call a realtime GC. And Lua does not have one. However it turns out that we can get very close to realtime with minor changes to the Lua GC.

The patch below modifies the behavior of the GC in the way we need it:

--- a/src/lgc.c
+++ b/src/lgc.c
@@ -609,15 +617,14 @@ static l_mem singlestep (lua_State *L) {
 void luaC_step (lua_State *L) {
   global_State *g = G(L);
-  l_mem lim = (GCSTEPSIZE/100) * g->gcstepmul;
-  if (lim == 0)
-    lim = (MAX_LUMEM-1)/2;  /* no limit */
   g->gcdept += g->totalbytes - g->GCthreshold;
+  double start = getTime();
+  double end = start + (double)g->gcstepmul / 1000.0;  
   do {
-    lim -= singlestep(L);
+    singlestep(L);
     if (g->gcstate == GCSpause)
-  } while (lim > 0);
+  } while (getTime() < end);
   if (g->gcstate != GCSpause) {
     if (g->gcdept < GCSTEPSIZE)
       g->GCthreshold = g->totalbytes + GCSTEPSIZE;  /* - lim/g->gcstepmul;*/

The only missing part from the patch above is the getTime() that can be something like this:

double getTime() {
    struct timeval tp;
    gettimeofday(&tp, NULL);
    return (tp.tv_sec) + tp.tv_usec/1000000.0;

I guess however that everyone will want to use their own time function.

The patch modifies the code so that is stops based on a time limit and not based on a calculated target memory amount to be freed. The simplicity of the patch also comes from the fact that we “reuse” the STEPMUL parameter that is no longer used to carry the aggressiveness of the GC. We now use it to hold the exact duration we want the GC to run in milliseconds. So the usage will be this:

lua_gc(L, LUA_GCSETSTEPMUL, gcMilliSeconds);
lua_gc(L, LUA_GCSTEP, 0);

The above code will run the GC for gcMilliSeconds ms. This way you will never be out of your frame time budget, because the garbage collection took a little longer to execute. Problem solved!

Hollywood Directors Beware!

With great pleasure I inform you that my first video clip is complete! No I am not singing.. I just created the video for the upcoming single from Dol Theeta – the second brain child of Thanasis Lightbridge. Part of the three band project of his, of which we only experienced Dol Ammad until now. Judging from the single that I had the privilege to work with, the whole project is Continue reading

24 hours and 3GB later…

Its been almost 24 hours since the release of Sylphis3D and the sourceforge shows that 3GBytes were downloaded already about 10 e-mails expressing unbounded appreciation and some very nice comments. People are already jumping in to help with the website, doing changes and cleaning up the mess!

I would like to thank every one of you for your good wishes and I hope the best for you, too.

The wait is over… Sylphis3D is open source!

I just release the source to Sylphis3D! Check out the story at the Developer Network.

The wait is over! Sylphis3D is officially released under the GNU GPL ver.2 (with the classpath exception for those that need closed source solutions). The engine weights at around 45000 lines of source code written in C++ and Python. The source code can be obtained from the download page of the [ project page]( Latter on the source will be added to the subversion repository for easier access. The source code compiles under Microsoft Visual Studio .NET 2003. The makefiles and sconsturct files, for compiling with GCC, are out of date. However the mapcompiler is up to date. The source would compile out of the box. Continue reading

Tomorrow the Release

The time has come… tomorrow is the release day of Sylphis3D as an open source project. I’m very excited for this new begining! This is going to be my biggest contribution to the open source community until now.

The source that is going to be released counts ~45000 lines of code in C++ and Python counted with SLOCCount and the development cost was evaluated at $1.500.000 !!!

Oh.. well…. 🙂

sylphis3d, release, open source, GPL, 3d, engine, opengl

Opensource License

The last days I’m spending most of my time considering open source licenses and what would be the appropriate license for Sylphis3D. I must say that it is a very brain-melting procedure. I can see now why I could never became a lawyer!

I initially started considering two licenses, the GPL and the BSD. These are both approved open source licenses by the FSF. GPL is the defacto open source license today and has proven its value. Most of open source software today is released under the GPL, including Linux. The license was proven to be able to protect and empower the freedom of the software, by forcing code to be contributed back to the original GPLed software. The BSD on the other side is a more liberal license. Requires for the adopters of the code to make no more than to mention the code that was used. They are not required to release their code back. This is looked upon by some open source people because it allows closed source projects to benefit from open source, without ever contributing back. The classic example here is the Windows operating system that used the networking stack of the freeBSD operating system; no code was ever contributed back by Microsoft.

The problem with GPL is that it is not an easy solution when it comes to 3D game engines. A GPLed engine Continue reading