Compilation Options

(Note that wherever "MiniD" is mentioned, it's mostly referring to "the reference D implementation of MiniD, the library" and not to the language. The language doesn't really have any restrictions.)

MiniD provides some options that you can use to enable or disable certain features for purposes of library size, D heap allocation, flexibility, and extra features.

Integer Size

By default, MiniD's int type is defined as a signed integer the same size as the native word size integer of the host machine. So on x86, it'll be 32 bits, and on x64, it'll be 64 bits. But if you want to force the integers to be a certain size, you can do so with the MDForceLongInts and MDForceShortInts versions. MDForceLongInts forces them to be 64 bits on any platform, and MDForceShortInts forces them to be 32 bits on any platform. If you define both, it is an error. If you define neither, the default behavior is used.

Coroutine Support

MiniD has three levels of coroutine support: restricted, normal, and extended.

Restricted coroutine support is the most basic level. In this mode, you may only create coroutines using MiniD (script) functions as the coroutine bodies. Yielding is restricted in that a coroutine may only yield if there are no native calls or metamethod calls on the call stack of that coroutine. The yield native API function is also absent.

Normal coroutine support lifts the restriction on what kinds of functions can be used for coroutines, allowing native functions to be used as coroutine bodies. The yield native API function exists. However, the restriction on yielding out of script coroutines with native/metatmethod calls still exists. Yields can be performed out of native coroutines if native/metamethod calls exist, however.

Extended coroutine support goes one step further and removes all yielding restrictions. Coroutines can be created with script or native functions as their bodies, and yields can be performed anywhere with no restrictions.

The reason for the three levels of support are due to the fact that in order to lift the restrictions imposed by the restricted mode, native coroutine objects (the tango.core.Thread.Fiber class) must be created. This involves performing a D heap allocation, which may not be desirable, as this could trigger a GC cycle in the host application (which, in a real-time application like a game, might not be acceptable).

For those who don't want their scripts triggering GC cycles in the host at all, the restricted option is the way to go.

Normal coroutine support should be fine for most scripts, as a large majority of coroutines tend to be script-only. A native coroutine object is only allocated for coroutines created with a native function as the body. Script coroutines are handled as in restricted mode.

For those who don't mind the extra allocations, or who really need to be able to yield anywhere, the extended coroutine mode is the most flexible, at the cost of allocating a native coroutine object for every MiniD coroutine.

A word on performance: when native coroutine objects are used, yielding and resuming are slightly slower than when the script coroutine support is used. However, this is a tiny, tiny fraction of the time that will be spent executing your code. The amount of time used to execute the body of the coroutine will likely far exceed the slight loss of performance due to the slower yields and resumes. Even using native coroutine objects, MiniD still beats most other languages in the cheap-concurrency benchmark from the Great Computer Language Shootout. (well, at least when that benchmark existed, it did.)

Using native coroutine objects also uses a bit more memory. Each object consumes around 4 extra KB, as long as the native call depth within the coroutine doesn't go too deep.

If you want to use restricted mode, define the MDRestrictedCoro version. If you want to use extended mode, define the MDExtendedCoro version. Defining both is an error. If you define neither, normal coroutine mode will be used.