Launcher

This component keeps track of information useful when launching applications: it keeps track of how much memory is available and how well sleeping applications fit into that memory. This component resides in the system module. Thus, to interact with it, your program will probably use a syntax like that in the following example:

system:launcher!RequestMemory( 2 ) REM We'll need another 2K soon

Applications which will handle Launcher events can create their own Launcher components.

Launcher Properties

Standard Properties
class, parent, proto, version.

memoryAvailable integer
This read-only property reflects the estimated amount of free heap memory available for loading applications.

The value decreases when applications are loaded, and increases when they are unloaded.

When this value becomes negative _memoryDemand() events will be raised, which cause the system to attempt to unload sleeping applications. This should get memoryAvailable back above zero.

The memoryAvailable value is typically less than the actual amount of free memory, as the system needs to keep a certain amount in reserve to allow for fragmentation and sudden rushes in memory use before protection mechanisms can react.

memoryReserve integer
This read-only property holds the amount of memory to subtract from the true number of free kilobytes when calculating memoryAvailable.

Designed to insure that there is always some memory around when memoryAvailable becomes negative. Specifically, this value has to be large enough such that if memoryAvailable is sitting at 0, and a large allocation occurs, there will be enough memory left to unload applications before we actually run out of memory.

Launcher Events

_hardIconPressed()

_hardIconPressed( self AS launcher, icon AS integer )

This event is generated when the user presses one of the device's "hard icons." Typically, an application's Launcher won't do anything at this point, but will instead allow the system Launcher to do its thing.

Pass:

self launcher
The component experiencing the event

icon integer (range is device-specific)
Which icon was tapped.

_hide()

_hide( self AS launcher, application AS string )

The launcher should respond to this event by hiding the named application. This normally means calling that application's module_hide() routine, and the module_show() routine of some other application.

Pass:

self launcher
The component experiencing the event.

application string
The application to hide.

_memoryDemand()

_memoryDemand( self AS launcher, memoryDemanded AS integer )

This event is generated whenever memoryAvailable becomes negative--however, if there is more than one Launcher component active on the device when this happens, not all of them will necessarily detect this event. The youngest Launcher will first have a chance to handle the event--if it can free up enough memory such that memoryAvailable goes positive, then other launchers will never generate the event. If it can't free up enough memory, the next youngest Launcher will generate the event, and get its chance to free up memory. Finally, if no other Launcher can free up enough memory, the system Launcher will unload some applications.

When this event is generated, any flushable applications in the cache should already have been flushed by the _memoryRequest() handler in the system module.

Chances are, there is an application that is using too much memory; it should now be unloaded (with apology) to the user. The next possibility is that too many apps are attempting to keep from being unloaded by setting preventUnload to non-zero. These should be unloaded at this time, because the system is very low on memory.

Pass:

self launcher
The component experiencing the event.

memoryDemanded integer(0-32767)
The amount of memory, in kilobytes, demanded.

_memoryRequest()

_memoryRequest( self AS launcher, memoryNeeded AS integer )

This event is generated whenever a RequestMemory() action is invoked that requests more memory than is available. If possible, sufficient memory to honor the request should be freed up in this handler.

Applications or modules that can reduce the amount of memory they are using can have their own Launcher component, and handle this event by reducing their memory usage. Otherwise, the system Launcher component may unload some applications that are currently loaded but not in use.

If there is more than one Launcher component, the memoryRequest event will be generated for as many of them as it takes to free up the requested memory. The components will generate the events in order from youngest to oldest. The system module's Launcher component will get the event last, after any loaded applications free as much memory as they can.

Pass:

self launcher
The component experiencing the event.

memoryDemanded integer (0-32767)
The amount of memory demanded, measured in kilobytes.

_outOfMemory()

_outOfMemory( self AS launcher )

This event is generated if the system is in dire trouble. If an application has demanded memory, and no Launcher has been able to free up enough memory, this event is generated. The system has severe memory problems, perhaps severe fragmentation or a memory leak.

After all applications' Launchers have had their chance to handle this event, the system Launcher module will apologize to the user and reboot.

Pass:

self Launcher
The component experiencing the event.

_setContext()

_setContext( self AS launcher, application AS string, context AS string )

This event is generated when the Launcher tries to "go to" a specific context within a specific application. The application should be brought to the front if running, loaded if it's not running. The typical handler for this event will do what the handler for the _switchTo() event does, except that it will pass the supplied context string to the application's module_goTo() routine.

Pass:

self launcher
The component experiencing the event.

application string
A module locator string for the governing module of an application, like those passed to LoadModule().

context string
Context as passed to the module_goTo() routine of the application module. The null string ("") may be passed to invoke the application in its initialized state.

_switchTo()

_switchTo( self AS launcher, application AS string )

This event is generated when this Launcher wants to switch to an application, as the result of the SwitchTo() action. A handler for this action will normally proceed as follows:

  • If the specified application is already loaded and active, the handler should do nothing.
  • If there is a currently active application, the handler should "hide" the application. This involves calling the application's module_hide() routine.
  • If the application is not currently loaded, the handler should load it and call its module_goTo() routine with the context it returned the last time it was closed (this context should probably be stored in a database). Note that memoryAvailable should be examined here and if necessary RequestMemory() called to insure there is enough memory.
  • The handler should then call module_show() on the application being switched to.
  • If a new application has been loaded, the module variable should be stored in a list of loaded application modules (this makes step 3 easier).
  • The code should note that the given application has been switched to, for implementation of a LRU unloading scheme--handy in case we need to unload older applications when memory gets low.

Pass:

self launcher
The component experiencing the event.

application string
A string describing the location of the module to switch to--as you might pass to LoadModule().

Launcher Actions

Hide()

Hide( application AS string )

Use this action to hide an application and to show another application.

Pass:

application string
The application to hide.

RequestMemory()

RequestMemory( memoryRequested AS integer ) AS integer

Requests that the system free memory for upcoming use. This action, intelligently used, can minimize user-perceived delays.

This function is good to call from strategic points in an application where the application knows it will need more memory soon and the user is likely to tolerate a delay.

If sufficient memory was not freed, then the action will return zero.

SetContext()

SetContext( application AS string, context AS string )

Use this action to go to a particular context within a specified application.

If you're using your own Launcher component, this action will generate a _setContext() event.

SwitchTo()

SwitchTo( application AS string ) AS string

Use this action to switch to an application: to load the application if it's not already loaded, and to bring it to the front.

If you're using your own Launcher component instead of the system's Launcher, invoking this event generates a SwitchTo() action.