# 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:

- Prefix 'l'
Methods prefixed with 'l' are called while LCDUILock is locked. Code within these methods has free access to LCDUI class and instance variables. Code within these methods must not call out to the application.
- Prefix 'u'
Methods prefixed with 'u' are called while LCDUILock is unlocked. Code within these methods must first lock LCDUILock prior to any access to class or instance variables. Code within these methods may call out to the application, but it may do so only while LCDUILock is not held and while calloutLock is held.

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

- Prefix 'uCall'
A prefix of 'uCall' implies everything that the 'u' prefix implies, with the following additional characteristics. Methods prefixed with 'uCall' are called only from the event dispatch thread while LCDUILock is unlocked. These methods may end up calling into application code, handling LCDUILock and calloutLock appropriately. A subclass may override methods with this prefix if it needs to perform an additional callout to application code. Otherwise, it should only override the 'lCall' version explained below.
- Prefix 'lCall'
Methods prefixed with 'lCall' contain implementation code that is shared by 'uCall' methods. As with other methods with the 'l' prefix, methods prefixed with 'lCall' are called while LCDUILock is held. Note that 'lCall' methods do not actually call out to the application. They are named as such because they assist 'uCall' methods. In all cases it is the responsibility of 'uCall' methods to perform the actual callout to the application. An 'lCall' method may be overriden by subclass to perform additional work that does not involve calling out to application code.
- Prefix 'lRequest'
Methods prefixed with 'lRequest' initiate some action by posting an asynchronous event to the event queue. The method returns immediately and does not wait for the event to be processed. The requested action is performed at a later time, when the event is processed. As with other methods that have the 'l' prefix, these methods must be called while LCDUILock is held.

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.