Hero RSL Enhancements - Functional and Design Specification

Glossary

Default RSLs: The RSLs specified in flex-config.xml. When an application is linking with RSLs the list of RSLs in flex-config.xml will be used unless overridden by other configuration files or the command line.

Flex Startup Information: Every application and module has compiler generated code for a root class. For example, the name of the root class for an application named AppName is _AppName_mx_managers_SystemManger.as. The name of the root class for a module named ModuleName is _ModuleName_mx_modules_FlexModuleFactory.as. Each root class has an "info" function from the IFlexModuleFactory interface. The info function returns an Object which is statically defined. The RSLs to be loaded are retrieved from this object. The string used retrieve the RSLs and the format of the RSL information may change from build to build.

Soft-link: Soft-linking is referring to a class indirectly by using a quoted string in the source code. At runtime the class definition is obtained by calling getDefinition(). Since the class name is not reference directly, the compiler will not link it into the application unless the class is referenced via some other class.

Summary and Background

This feature is a grab bag of mini-features to make RSLs easier to use and more effective.

Background
Using signed RSLs with the Flash Player Cache was introduced in Flex 3. In Flex 3 we only had three RSLs and only the framework RSL was loaded by default. RSL linkage was off by default.

In Flex 4 we turned RSLs on by default and allowed RSLs to be debugged but no made major changes to how RSL are configured or loaded. We added five default RSLs, making for a total of six RSLs that are loaded by default for every application.

RSLs were designed very simply. You specify the SWC you want to be an external library and we load the RSL from the URL you told us contains all of the classes required to make the application work. RSLs need some feature work to catch up to the demands that the SDK and customers are putting on them.

For more background information please see http://opensource.adobe.com/wiki/display/flexsdk/Linking+RSLs+by+Default.

Problems

1. The number of default RSLs grew from one in Flex 3 to six in Flex 4. Loading all the RSLs delays application start up. All the default RSLs need to be loaded even if they are not used by the application.
2. When compiling an application it is not clear whether you are compiling with RSLs or where the RSLs will be loaded from. This due to RSLs being controlled in flex-config.xml instead of at the command line.
3. Going into Flex 4 we only expected sub-applications and modules to re-use the RSLs loaded by the main application. But now we see modules that are being used to load custom RSLs. Expecting the main application to load all of the RSLs won't work anymore. We are also seeing cases where modules want to be independent of the application and load all the RSLs it needs without regard for which RSLs the application is loading. Today this can result in multiple loads of the same RSL.
4. Monkey patchers can create RSLs to override classes in the signed SDK RSLs but the process is more difficult than it needs to be. A monkey patcher needs to figure out the inheritance dependencies of the classes they are monkey patching and then modify their existing projects to insert the monkey patch RSL in the load order.
5. The Spark components are nearing feature parity with mx components. The mx components are in the framework RSL and won't be used in most cases. The mx components are making the framework RSL larger on disk and in-memory than it needs to be.

Solutions

1. The compiler removes RSLs that are not used by the application. A new compiler option, remove-unused-rsls, will be added to remove RSLs that are not used by the application. This capability will allow the SDK to specify all the RSLs as default RSLs and rely on the compiler to only load the required RSLs. Allow the developer to have the final say on which RSLs are loaded by providing an option to force the loading of a given RSL.
2. At compile time output the list of RSLs required by an application. This reminds the user that they are using RSLs and the expected location of the RSLs. Since not all default RSLs may be required a developer can see which ones are really needed.
3. If a sub-application or module tries to load an RSL that has already been loaded, then skip loading that RSL.
4. To help out monkey patchers we can add a compiler switch to only include inheritance dependencies in a SWC that will be used as a monkey patch RSL.
5. Move the mx components to a new SWC and a separate RSL so they are only loaded if needed by the application.

Usage Scenarios

Remove unused RSLs

In Flex4 it was important to consider which SWCs were using RSL linkage by default since all RSLs would be loaded at runtime. Now that unused RSLs can be removed any SWC that has an RSL can use RSL linkage by default. The compiler will be able remove RSLs that are not used.

Do not load RSLs that have already been loaded.

Joe is developing modules that can be loaded by any application. He wants to take advantage of RSLs size reduction but he can't guarantee that an application will load the RSLs he needs. The module would sometimes load RSLs that were already loaded just to make sure the RSL was available. He notices that after recompiling with the new SDK that the module no longer loads RSLs that have been loaded by the main application.

Monkey Patch: inheritance dependencies only

Jim is monkey patching mx.collections.ListCollectionView. He also wants the monkey patch to work when using RSLs so he decides to create an RSL with his monkey patch. In order to get the smallest possible RSL he figures out all the inheritance dependencies of ListCollectionView by hand and externalizes all classes except ListCollectionView and its inheritance dependencies. When using Flex 4.5 he can just use the include-inheritance-dependencies-only options and get the same end result.

Detailed Description

Remove unused RSLs

The compiler will look at the classes used by an application and determine which libraries are used. When the set of RSLs is written to the Flex Startup Information, only RSLs that contain classes used by the application will be written out. This restricts the number of RSLs loaded by the application at runtime.

When linking with RSLs the compiler will output the list of RSLs that it found to be required. The lists gives the user feedback that RSL linking is being used and the what the urls of the required RSLs are.

There is a compiler option, force-rsls, for a developer to force an RSL to be loaded. This option may be needed if classes in the RSL are only referenced indirectly via soft-links. The force-rsls option takes a SWC as an parameter. The SWC must have been specified in a runtime-shared-library-path option or an error is displayed:

c:\opensource\sdk\trunk\frameworks\libs\osmf.swc was used in the force-rsls option
without being configured in the runtime-shared-library-path option.

Limitation for pre-Flex3 RSLs

These options only deal with RSLs with digests, specified using runtime-shared-library-path. They have no impact on RSLs without digests, specified using runtime-shared-libraries. The runtime-shared-libraries option is a pre-Flex3 way of loading RSLs. It is maintained for backwards compatibility. The limitation exists because the values specified using runtime-shared-libraries only specify RSL URLs to load. There is no SWC associated with RSLs so there is no way to automatically exclude them.

Compiler options

-remove-unused-rsls=[true | false]

Enables the compiler to remove unused RSLs. This is false by default for backwards compatibility.
alias: -remove-usused-rsls.

-runtime-shared-library-settings.force-rsls=[path-element]

Enables to user to force the loading of an RSL. Multiple path-elements may be specified.
path-element: The path of a Flex library file. The RSL associated with this library will be loaded at runtime. It is an error to specify a library file that does not have an RSL associated with it.
alias: -force-rsls.

Do not load RSLs that have already been loaded.

Before an RSL is loaded, the application or module loading the RSL will ask its parent if an RSL with the given URL has already been loaded. If the RSL has already been loaded, then it will be skipped.

Split the mx components out of framework.swc

Create a new project and SWC for the mx component set. The name of the new library is mx.swc. The framework.swc will no longer contain any mx components. The framework.swc will just contain core classes common to both Spark and mx components.

The MX components moved from framework.swc to mx.swc:

Accordion
AccordionHeader
AddChildAction
AddItemAction
Alert
Application
ApplicationControlBar
Box
Button
ButtonBar
ButtonBarButton
CalendarLayout
Canvas
CheckBox
ColorPicker
ComboBox
Container
ControlBar
DataGrid
DataGridColumn
DataGridItemRenderer
DateChooser
DateField
DefaultListEffect"
DefaultTileListEffect
DividedBox
Form
FormHeading
FormItem
FormItemLabel
Glow
Grid
GridItem
GridRow
HBox
HDividedBox
HorizontalList
HRule
HScrollBar
HSlider
Image
Label
LinkBar
LinkButton
List
ListBase
Menu
MenuBar
MenuBarItem
Module
ModuleLoader
NumericStepper
Panel
PopUpButton
PopUpMenuButton
PrintDataGrid
RadioButton
RadioButtonGroup
RemoveChildAction
RemoveItemAction
Repeater
Resize
RichTextEditor
ScrollBar
ScrollControlBase
SetPropertyAction
Slider
SwatchPanel
Tab
TabBar
TabNavigator
Text
TextArea
TextInput
Tile
TileList
TitleWindow
ToggleButtonBar
ToolBar
Tree
UnconstrainItemAction
VBox
VDividedBox
VideoDisplay
ViewStack
VRule
VScrollBar
VSlider
WipeDown
WipeLeft
WipeRight
WipeUp

Monkey Patch: Compiler option to create RSLs with only inheritance dependencies

When creating a SWC for a monkey patch RSL, the SWC needs to be as small as possible. If you are monkey patching a class such as mx.collections.ListCollectionView, then you would ideally only want that class in the RSL. But the Actionscript virtual machine also requires inheritance dependencies of a loaded class be available as well. See http://www.adobe.com/devnet/actionscript/articles/avm2overview.pdf, Section 3.2 Loading and linking.

This feature adds a compiler option to compc to include only the inheritance dependencies of a set of classes specified in the include-classes option. Other classes that are only used by ListCollectionView are not included. This feature only works with classes included using the include-class option.

API Description

Remove unused RSLs

This describes Compiler API to allow Flash Builder to set the configuration options for remove-unused-rsls and force-rsl.

/**
* Enables the removal of RSLs associated with libraries
* that are not used by an application.
* This is equivalent to using the
* remove-unused-rsls option of the mxmlc compiler.
*
*


* The default value is false.
*
* @param b Boolean value that enables or disables the removal.
*
* @since 4.5
*/
void removeUnusedRuntimeSharedLibraryPaths(boolean b);

/**
* Sets the SWCs that will have their associated RSLs loaded at runtime.
* The RSLs will be loaded whether they are used in the application or not.
* This option can be used to override decisions made by the compiler when
* using the removed-used-rsls option.
*
* This is equivalent to using the
* runtime-shared-library-settings.force-rsls option of the
* mxmlc compiler.
*
* @param paths An array of File objects. Each File
* instance should represent a SWC file. May not be null.
*
* @since 4.5
* @throws NullPointerException if path is null.
*/
void setForceRuntimeSharedLibraryPaths(File[] paths);

/**
* Adds SWCs to the existing set of SWCs whose RSLs will be loaded at runtime.
*
* This is equivalent to using the
* runtime-shared-library-settings.force-rsls option of the
* mxmlc compiler.
*
* @param paths An array of File objects. Each File
* instance should represent a SWC file. May not be null.
*
* @since 4.5
* @see #setForceRuntimeSharedLibraryPaths(File[])
* @throws NullPointerException if path is null.
*/
void addForceRuntimeSharedLibraryPaths(File[] paths);

B Features

*Have the compiler figure out RSL dependencies and load independent RSLs in parallel to reduce download time.
*Some application developers need to modify an RSL URL at runtime based on application parameters. The solution is to create an API for an RSL loader. The user will specify their RSL loader class as they specify preloader classes today. The RSL loader will override the SDK RSL loader and give the user complete control. Priority B.
**We can also add a compiler switch to insert an RSL either before or after an RSL that is already in the load order. This allows a developer to modify the default RSLs without copying and pasting them into a local configuration file. Priority B.
**Compiler API to optimize an RSL. When a SWC contains custom metadata to preserve, optimizing the RSL requires adding the metadata as an argument to the optimizer tool. Most people don't know that or forget. Last I knew Flash Builder didn't not do that as will. The API call would improve our tooling. Priority B.
**Provide better feedback as RSLs are downloaded by providing the download progress bar with RSL sizes. Priority B.

Examples and Usage

Remove unused RSLs

mxmlc main.mxml -force-rsls={flexlib}\libs\osmf.swc

The RSL associated with osmf.swc is loaded by the application even if no classes in osmf.swc are referenced by the application.

When compiling a simple shell program the output describing which RSLs are required will look similar to this:

C:\tests\helloworld>mxmlc main.mxml -remove-unused-rsls -static-rsls=false
Loading configuration file C:\opensource\sdk\trunk\frameworks\flex-config.xml
Required RSLs:
textLayout_1.1.0.603.swf
framework_4.0.0.0.swf
spark_4.0.0.0.swf
sparkskins_4.0.0.0.swf
C:\tests\helloworld\main.swf (38261 bytes)

Monkey Patch: Compiler option to create RSLs with only inheritance dependencies

compc -include-classes mx.collections.ListCollectionView
-include-inheritance-dependencies-only
-source-path . -output lcv2 -directory

Additional Implementation Details

None.

Compiler Work

Described in the Detailed Description section.

Backwards Compatibility

Syntax changes

None.

Behavior

The compiler option to remove unused RSLs will default to true to force developers to opt-out of the new behavior. It is important to remove unused RSLs because with this feature all of the SDK RSLs can be made default RSLs. If the unused RSLs are not removed the load time of all applications will be increased.

There is a backwards compatibility issue for some applications that are compiled with command line tools and use modules. We have been telling SDK users to have the main application load the RSLs and compile modules with the associated SWCs on the external library path. When we default to removing unused RSLs then the main application may not load an RSL that a module needs. If this happens the module will RTE at runtime.

Warnings/Deprecation

None.

Accessibility

None.

Performance

When using RSLs, start up time is improved in 4.5 compared with 4.0. The improvements in start up time come from not downloading RSLs that are not used by an application and the reduction in size of the framework RSL.

The test application was a simple "Hello World" application. This is not a typical application but it demonstrates the maximum start up benefit the can be obtained from using this feature.

<?xml version="1.0" encoding="utf-8"?>
<s:Application
xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:mx="library://ns.adobe.com/flex/halo"
    xmlns:s="library://ns.adobe.com/flex/spark"
    applicationComplete="appComplete()">

    <fx:Script>
        <![CDATA[
            private function appComplete():void
	    {
		startUpTime.text+= String(getTimer());
                memoryUsage.text += String(System.totalMemory);
            }

        ]]>
    </fx:Script>

    <s:Label text="Hello World"/>
    <s:Label id="startUpTime" text="start up time = " x ="300" y="0" />
    <s:Label id="memoryUsage" text="memory = " x ="300" y="35" />

</s:Application> 

The application was compiled with 4.0 and with 4.5 using the "remove-unused-rsls" compiler option. This resulted in the 4.5 application not downloading the osmf RSL and the rpc RSL compared with the 4.0 application downloading the textLayout, osmf, framework, spark, sparkskins, and rpc RSLs. In addition, the size of the framework RSL in 4.5 has been reduced from 608 KB to 310 KB. The reduction in size was the result of moving the mx components out of the framework an into there own mx library.

The test was run by throttling the download rate to 1500 kbps and downloading the 4.0 and 4.5 versions of the "Hello World" application.

The application compiled with 4.5 shows an improvement of 6 seconds in download time and a saving of 3.4 MB of system memory.

Globalization

None.

Localization

Framework Features

None.

Cross-Platform Considerations

None.

Issues and Recommendations

None.