Investigating USER handles with the SWT Detective

What to do when your SWT application runs out of user handles.

"No more handles." Have you ever got this error message in your SWT application? We've had reports of this error cropping up in our Sophora DeskClient when the user had a lot of documents open simultaneously. To investigate this error, we first needed to know the kind of the unavailable handles. These could be e.g., file or GDI handles, but in our case turned out to be USER handles.

So what is a USER handle? The windows system uses user handles to reference objects used in the user interface. They includes windows, menus, fonts, images, menu accelerator tables and probably some other stuff. SWT uses mostly native controls, so each SWT window, menu etc. will use a corresponding user object. Actually, SWT uses a user object for each widget, even for plain Composites. The total number of user objects used by an application can be shown using the excellent process explorer. Our application has a lot of widgets, so we are using a lot of user objects. Now why is this a problem? Turns out that due to its 16-bit legacy, Windows has a limit of 32k user objects per desktop session, and an additional limit of 10000 user objects per process. And with 20+ documents open at the same time, our DeskClient was hitting this limit. Incidentally, this is only a problem on windows, linux and mac are not affected.

To reduce the number of user objects used by an application, the options are fairly limited. First we made sure that we were not leaking any images or widgets. Then we looked for ways to reduce the number of SWT widgets that are on screen at the same time. To do this we investigated the widget tree of our application. This is where the SWT Detective comes in. The SWT Detective is an Eclipse plugin based on the SWT Spy that is included in the SWT Tools package. It shows information about the widget under the mouse cursor. It differs in the following aspects from the SWT Spy:

• The child tree of the selected widget is shown.
• The parents and peers of the selected widget are not shown by default. The display can be toggled using buttons.
• The widget tree displays widget-specific information, e.g. the text content of a Text or StyledText control, the title of a Section, or the first entry of a Tree or Table.
• The widget data object (or keyed objects) are shown.
• Instead of showing information about the widget under the mouse cursor, the SWT Detective can also show the entire widget tree of the application.
• There is a refresh button and other small improvements.

The screenshot shows the SWT Detective with information about the form section with the blue background on the left. In this example, each form field and some of the form labels are wrapped in a LayoutComposite. These composites are probably used for layout purposes only and can possibly be removed if the layout of the form section is done using a sophisticated layout manager. Another optimiziation we have done is to lazy-load the tabs in this multi-page editor. The content of each tab is only created when the tab is opened for the first time. And finally, we turned to use windowless controls in some cases. A windowless control draws its content itself instead of being a composite of other base widgets. In the Sophora DeskClient, each search result entry is a widget that used to be made of a bunch of labels and images but is now entirely custom-drawn. It now uses only one user object instead of about 10.

To recap, reduce the number of SWT widgets / Windows user objects by:

• avoiding resource leaks
• not using Composite objects for layout purposes
• using lazy-loading of ui elements
• drawing custom widgets yourself instead of composing base widgets

So there's no silver bullet, but these measures combined significantly reduced the number of user objects used by the Sophora DeskClient. Now our users can have lots more documents open at the same time.

Download

SWT Detective