Threads with FreeType
=====================
The FreeType engine can now be compiled in thread-safe mode.
Because we want to keep the engine small and fast, the thread
protection is simple. This file gives an overview of what you can
do, and what you should strictly never do.
How to enable thread-safe support?
A. You must have a valid replacement for the file `lib/ttmutex.c'
which calls your system's API to create, lock, and release
mutexes or semaphores. The current implementation is a dummy and
doesn't do anything.
B. You must re-define the configuration macro
TT_CONFIG_OPTION_THREAD_SAFE located in `ttconfig.h'. Then
recompile.
IMPORTANT NOTE:
If two threads create and use their own TT_Engine structure, they
can freely call the library concurrently on each of them (as well
as all their related objects), even in the non-threaded build.
The following remarks only apply to concurrent requests performed
on a single TT_Engine shared by multiple threads.
--------------------------------------------------------------------
- What you can do:
With the exceptions listed below (in `What you can't do'), you can
call all API functions concurrently with two different threads.
This includes:
Creating two or more faces from the same engine (i.e. concurrent
calls to TT_Open_Face()/TT_Open_Collection()).
Creating two or more instances from the same face object
(i.e. concurrent calls to TT_New_Instance()).
Creating two or more glyph containers from the same face object
(i.e. concurrent calls to TT_New_Glyph()).
The same holds for destruction of objects.
Load two or more glyphs concurrently for the same face or
instance (i.e. concurrent TT_Load_Glyph() calls).
Render two or more glyphs at the same time, in the same engine
(i.e. calling TT_Get_Glyph_Bitmap()/TT_Get_Glyph_Pixmap() or
TT_Get_Outline_Bitmap()/TT_GetOutline_Pixmap() concurrently).
NOTE: The scan-line converter can only render one glyph at a
time, for a given TT_Engine. Concurrent calls are
synchronized through a mutex, though.
If you really, _really_, need to generate bitmaps or
pixmaps concurrently, create an additional engine and use
it with TT_Get_Outline_Bitmap()/TT_Get_Outline_Pixmap()
(you don't need to create any object in it, the outline
can come from any source too).
This is, however, not recommended (it works perfectly, but
this could change in the future for various technical
reasons).
---------------------------------------------------------------------------
- What you cannot do:
- You shouldn't try to delete an object while still using it with
another thread. The engine doesn't protect you from stupidity!
For example, these concurrent calls:
TT_Close_Face( face );
TT_Get_Glyph_Bitmap( glyph, &bitmap );
will act unexpectedly if the glyph is a child of the face (i.e.,
was created with TT_New_Glyph( face, &glyph ))
^^^^
same face
Here are some other examples:
TT_Get_Glyph_Outline( glyph1, ... );
TT_Load_Glyph( instance, glyph1, ... );
or
TT_Get_Outline_BBox( outline, &bbox );
TT_Transform_Outline( outline );
etc.
You get the idea: Only the face and instances are protected --
glyph containers and outlines should be thread-specific.
- You shouldn't initialize extensions in an engine concurrently
(which is what every mere mortal will do anyway :-).
That's about it. Now enjoy the lib ;-)
PS: See the `MT-Note' and `MT-Safe' remarks in ttapi.c for more
detailed information on each specific function.
--- end of threads.txt ---