[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]

If multiple tasks are manipulating layers on the same display they will be
sharing a Layer_Info structure and their use of it and its related data
structures need to be coordinated.  To ensure that a structure remains
cohesive, it should be operated on by only one task at a time.  The
Layer_Info encompasses all the layers existing on a single display.

LockLayerInfo() must be called whenever the visible portions of layers may
be affected, or when the Layer_Info structure is changed.

    void LockLayerInfo( struct Layer_Info *li );

The lock should be obtained whenever a layer is created, deleted sized or
moved, as the list of layers that is being managed by the Layer_Info data
structure must be updated.

It is not necessary to lock the Layer_Info data structure while rendering,
or when calling routines like ScrollLayer(), because layer sizes and
on-display positions are not being affected.

Use UnlockLayerInfo() when you have finished the layer operation:

    void UnlockLayerInfo( struct Layer_Info *li );

If you don't unlock the Layer_Info then any other task calling
LockLayerInfo() on the same Layer_Info structure will be blocked creating
a potential deadlock situation.

In addition to locking the Layer_Info structure, the layer itself should
be locked if it is shared between tasks so that only one task at a time
renders graphics to it.  LockLayer() is used to get exclusive graphics
output to a layer.

    void LockLayer( long dummy, struct Layer *layer );

If a graphics function is in process, the lock will return when the
function is completed.  Other tasks are blocked only if they attempt to
draw graphics into this layer, or try to obtain a lock on this layer. The
MoveLayer(), SizeLayer() and ScrollLayer() functions automatically lock
and unlock the layer they operate on.

UnlockLayer() should be used after the graphics operation to make the
layer available to other tasks again.

    void UnlockLayer( struct Layer *layer );

If more than one layer must be locked, then the LockLayer() calls should
be surrounded by LockLayerInfo() and UnlockLayerInfo() calls, to prevent
deadlock situations.

The layers library provides two additional functions, LockLayers() and
UnlockLayers(), for locking multiple layers.

    void LockLayers( struct Layer_Info *li );
    void UnlockLayers( struct Layer_Info *li );

LockLayers() is used to lock all layers in a single command.
UnlockLayers() releases the layers lock.  The system calls these routines
during the BehindLayer(), UpfrontLayer() and MoveLayerInFrontOf()
operations (described below).