Control throttling in Windows and Views

Throttling is a design pattern for controlling the use of resources, to improve overall system performance or end-user experience, by preventing processes from running as quickly or as often as they otherwise might. Background throttling, a feature of Chromium, on which OpenFin's software is based, conserves system resources in tabs that are not actively being used by preventing them from updating the rendering their contents.

OpenFin v38 introduces two properties which provide enhanced control over throttling behavior associated with Windows and Views.

throttling for Window and View objects
backgroundThrottling for Window objects

How it works

With OpenFin Window and View objects, throttling can be desirable when the corresponding UI objects are hidden, minimized, or inactive.

There are two types of execution that you might want to throttle for inactive UI objects:

Painter: Creating render frames and drawing them onto the UI object; when throttled, calls to requestAnimationFrame() on the object are not executed until the content is shown or activated. For inactive View objects, painter throttling is always enabled and cannot be disabled.
Scheduler: JavaScript code execution associated with a UI object, which can be useful to control in an OpenFin environment when raising interoperability messages.

You can add a backgroundThrottling property (boolean, default false) to Window objects. It applies to both types of throttling, which is the default behavior in Chromium. When it is true, the window is throttled even if it is not hidden or inactive.

You can add a throttling property to either Window or View objects.
On window objects, if throttling is defined, any value for backgroundThrottling is ignored.
The throttling property takes two or three values, depending on whether it is set on a Window or a View.

enabled: (Window and View objects) Both painter throttling and scheduler throttling are enabled.
scheduler-disabled: (Window and View objects) Scheduler throttling is disabled, meaning that code execution runs at full speed, but painter throttling is enabled.
disabled: (Window objects only) Throttling is disabled for both painter execution and scheduler execution, which therefore run at full speed, even when the Window is inactive.

How to do it

You can set throttling-related options in several ways.

In a manifest file as part of defaultWindowOptions or defaultViewOptions.
When creating a Platform programmatically, as part of PlatformWindowCreationOptions or PlatformViewCreationOptions.
When creating a Window or View programmatically, as part of WindowCreationOptions or ViewCreationOptions. This includes creating views as components of a Layout.

You can change the values the throttling-related properties after creation by calling updateOptions() on the Window or View.

The following sections show a few examples of setting or updating the throttling-related properties.

Disable scheduler throttling for all views in a platform

Excerpt of an application manifest file with this setting.

{
  "licenseKey": "LICENSE_KEY",
  "platform": { 
    "uuid": "PLATFORM_UUID",
    "name": "PLATFORM_NAME",
    "url": "MAIN_WINDOW_URL", 
    // Other platform options

    // Default settings for all View objects
    "defaultViewOptions": {
      // Default value for 'throttling' on views
      "throttling": 'scheduler-disabled',
      // Other default view options
    }
  }
}

Disable scheduler throttling for a specific view

const newLayout = {
  content: [
    {
      type: 'stack',
      content: [
        {
          type: 'component',
          componentName: 'view',
          componentState: {
            name: 'EXAMPLE_VIEW',
            url: 'TARGET_URL_FOR_EXAMPLE_VIEW'
            throttling: 'scheduler-disabled',
            // Other properties of this view
          }
        },
      // Other components of the stack
      ]
    }
  ]
};

Disable painter throttling for all windows a in platform

Excerpt of an application manifest file with this setting.

{
  "licenseKey": "LICENSE_KEY",
  "platform": { 
    "uuid": "PLATFORM_UUID",
    "name": "PLATFORM_NAME",
    "url": "MAIN_WINDOW_URL", 
    "autoshow": false,
    // Other platform options

    //Default options for all windows
    "defaultWindowOptions": {
      // Default value for 'backgroundThrottling' on windows
      "backgroundthrottling": false,
      //Other default window options
    }

  //Other platform options
  }
}

Override `backgroundThrottling` with `throttling` on a Window

try {
  const platform = await fin.Platform.start({
    uuid: 'PLATFORM_UUID',
    autoShow: false,
    // Other platform options

    //Default options for all windows
    defaultWindowOptions: {
      // Default value for throttling properties on windows
      backgroundthrottling: true, //This value is ignored
      throttling: 'disabled',

      //Other default window options
    }

    //Other platform options
  });
console.log('Platform is running', platform);
} catch(e) {
   console.error(e);
}

Dynamically update `throttling` on a Window

// Create an application
const app = await fin.Application.start({
   name: 'APP_NAME',
   uuid: 'APP_UUID',
   url: 'APP_URL',
   autoShow: true,
   defaultWindowOptions: {
       throttling: 'enabled',
   }
});

//Get the main window
const win = await app.getWindow();
// Update 'throttling'
await win.updateOptions({throttling: 'scheduler-disabled'})
// When the window is hidden, the scheduler is not throttled