LCDUI Method Naming Conventions

LCDUI uses a set of naming conventions to guide developers as to the locking context for each method. For a detailed discussion of the locking policy in LCDUI, please see the "Thread Safety" section of the Design Guide.

The naming convention applies primarily to calls between the public API (model) classes and the LF ("look and feel") classes. However, the convention is also applied elsewhere.

All data in LCDUI, including data in both the API classes and in the LF classes, is protected by a monitor lock on a single object, Display.LCDUILock. This lock must be held during access, read or write, to any class or instance variables of any API or LF classes within LCDUI. The monitor lock on the Display.calloutLock object must be held by any code that calls out to the application, whereas, the monitor lock on LCDUILock must not be held across such calls. This implies that LCDUILock must not be held across calls to internal methods that might call out to the application. This further implies that there is a mixture of code within LCDUI: some methods are called while the monitor lock on LCDUILock is held ("locked"), and some methods are called when it is not held ("unlocked").

The primary goal of the naming convention is therefore to distinguish methods that are called while LCDUILock is locked from those called while LCDUILock is unlocked. The first convention is as follows:

Additional naming conventions describe special actions that are likely to occur during this call that have some impact on thread safety.

There are a variety of methods that don't adhere to any of the conventions described above. Generally, these are methods internal to an API class or an LF class, and they are called while LCDUILock is held.