Section 4.3. The Life of an Application Instance

4.3. The Life of an Application Instance

An application instance is a process that runs in FlashCom. Each instance has:

• Its own script engine

• A namespace of streams and shared objects

• Persistent data that can be stored within its namespace

No two instances can share or update the same data directly, but they can play the same stream in a virtual stream directory (see Chapter 5).

FlashCom maintains a pool of threads for script processing, and each application uses one thread from this pool to execute server-side scripts in response to events such as loading an instance or a Flash client connecting to an instance. Server-side scripts should be designed to handle events quickly and then release the thread they are using. When an error is thrown in one instance, it will not affect the other instances.

FlashCom can run many different instances of the same application. Each instance is usually created by FlashCom in response to a connection request from a client. FlashCom receives the client's connection request and examines the RTMP address passed by the client to the server. The RTMP address forwarded by the client is the URI passed into the client-side NetConnection.connect( ) method. As described in Chapter 3, FlashCom extracts the application name and then runs an instance of the application. If no instance name is provided in the RTMP address, it creates an instance named _definst_ . Otherwise, it creates the instance named in the URI. Depending on how the application is scripted and how the server is configured, some time after the last client disconnects, the instance will be destroyed. Between the time an instance is created and destroyed , a number of things can happen. To simplify how things work, they are divided here into three sections: startup, midlife, and shutdown.

4.3.1. Startup

An instance is normally started by FlashCom when the first client attempts to connect to it. However, it may be started manually with the App Inspector or Administration Console, or an application instance can be made to start immediately after the server is started by setting the contents of the <LoadOnStartup> tag in an Application.xml file (see "Using load( ) to Include Other Script Files" later in this chapter for details on where to place the Application.xml file).

Notice that there are two key objects related to instance and client management. The application object is a singleton objectthere is only onethat represents the application instance. Each instance gets its own application object, which is an instance of the Application class. As shown in Example 4-2, you should add dynamic methods directly to the singleton instance, application , instead of Application.prototype . For example:

 application.onConnect = function (client, userName, password) {}; 

A Client object represents a client-side Flash movie attempting to connect to an application instance. There can be more than one Client object (one for each user ) for each application object. The methods and properties of the Application and Client classes are described in Macromedia's Server-Side Communication ActionScript Dictionary (available from http://download.macromedia.com/pub/flashcom/documentation/FlashCom_SS_ASD.pdf).

Here is the startup sequence:

1. The main.asc file is loaded, compiled, and executed.

2. Any files that were included using the load( ) method are loaded and executed. In turn , these files may load other files.

3. The application.onAppStart( ) method is called. The onAppStart( ) method is called only once and is often used to initialize the application object and the instance's shared object and stream resources.

4. If the instance has been started as a result of a client connection request using NetConnection.connect( ) , the application.onConnect( ) method is called and passed a Client object, representing the client Flash movie that tried to connect. Any optional parameters passed into connect( ) are also forwarded to the onConnect( ) method, where the client's connection request can be rejected, accepted, or left pending.

4.3.2. Midlife

Once the application instance has started, any number of clients can connect and disconnect from the instance. Whenever a Flash movie attempts to connect, the application.onConnect( ) method is called and passed a new Client object representing the client-side Flash movie. Client objects with accepted connections are kept in the application.clients array. Whenever an accepted client disconnects, the application.onDisconnect( ) method is called and passed a Client object that represents the client that has disconnected. A client can be disconnected due to network problems or problems on a remote workstation. FlashCom may not realize immediately that the client has disconnected. So, it is possible that, for a time, a Client object will not always represent a connected movie.

4.3.3. Shutdown

An instance may be unloaded by the server because it is consuming too much memory, or it may be shut down manually using the Admin Service. Barring these sorts of events, an instance is normally shut down some time after the last client disconnects. The delay between the last client disconnecting and the instance being shut down is designed to minimize the number of startups an instance must perform. This delay is controlled by three tags in three types of XML configuration files, as described in Table 4-2.

Table 4-2. Shutdown configuration tags

Tag name	Default	Location	Description
<ApplicationGC>	5	Server.xml	Interval, in minutes, when applications are asked whether they should check for instances to dispose of
<AppInstanceGC>	20	Vhost.xml	Interval, in minutes, when application instances can be checked for disposal
<MaxAppIdleTime>	1200	Application.xml	Number of seconds since the last client disconnected before the instance can be disposed of

The default values mean that every 5 minutes applications are asked whether it has been 20 minutes since they tried to dispose of their instances. If it has been 20 minutes and the last client disconnected more than 1200 seconds (20 minutes) ago, the instance will be disposed of. Unless the server is very busy, the default values will result in instances being disposed of between 20 and 25 minutes after the last client leaves . This might seem like a long delay, but it is a reasonable compromise between leaving the instance running unnecessarily and doing the extra work of shutting down and restarting an instance if another client tries to connect.

Before an instance is finally shut down, its application.onAppStop( ) method is called. If onAppStop( ) returns false , the instance will not be shut down. The onAppStop( ) method is normally used to clean up any resources related to the application that may need further attention before the instance is discarded.