Writing thread-safe widgets

From Agar

This section was marked as being a stub. You are welcome to help expand it.

When Agar is used in a multithreaded application, it is important to have thread-safe widgets. To simplify things, Agar handles locking at the AG_Object(3) level.

Important locks

The major locking devices involved in an Agar-GUI application are:

• Locks protecting Widget objects.
• The lock protecting the AG_Driver(3) VFS.

Writing thread-safe functions

In a widget implementation, thread safety comes into play when writing additional, public functions as part of a Widget class. However, you will almost never need to bother adding mutex structures to your widget structure - you can use the lock associated with your Widget object instead. This lock is acquired using AG_ObjectLock().

typedef struct my_widget {
	struct ag_widget _inherit;
	int myData;
} MyWidget;
 
...
 
void
MyWidget_SetMyData(MyWidget *w, int value)
{
	AG_ObjectLock(w);
	w->myData = value;
	AG_ObjectUnlock(w);
}

When not to use AG_ObjectLock()

In a number of contexts, it is not necessary at all to use AG_ObjectLock to access protected data, because the object lock is implicitely acquired by Agar. An object can be safely assumed to be locked in the following contexts:

• All event handler functions, because AG_PostEvent() implicitely locks the target object.
• The init() operation, because the widget has not yet been attached.
• The destroy() operation, because the widget has been detached.
• The Widget draw(), size_request() and size_allocate() routines, because the lock has been implicitely acquired.

See also

• AG_Threads(3), AG_Event(3)