Wednesday, July 14, 2010

Permgen problems and Running Eclipse on Java 1.6 update 21

People running Eclipse on windows using the latest Java 1.6 update 21 jvm from Oracle/Sun are noticing frequent vm crashes or freezes:
Unhandled event loop exception
PermGen space
As indicated in the Eclipse FAQ, there is a simple workaround for this problem, edit your eclipse.ini file and add -XX:MaxPermSize=256m below the -vmargs line:
-startup
plugins/org.eclipse.equinox.launcher_1.1.0.v20100507.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.win32.win32.x86_1.1.0.v20100503
-product
org.eclipse.epp.package.jee.product
--launcher.defaultAction
openFile
-showsplash
org.eclipse.platform
--launcher.XXMaxPermSize
256m
--launcher.defaultAction
openFile
-vmargs
-XX:MaxPermSize=256m
-Dosgi.requiredJavaVersion=1.5
-Xms40m
-Xmx512m

History and Explanations

Starting as far back as Eclipse 3.1 it was noticed that Eclipse uses a lot of "PermGen" memory under Sun VMs. Permgen memory is where .class file information is stored. The way to avoid this memory problem is to increase the permgen size by using -XX:MaxPermSize.

The problem is that this is a non-standard vm argument and can cause vms from other vendors to not start at all. We eventually fixed this by introducing a new argument in the eclipse.ini file: --launcher.XXMaxPermSize.

When this argument is specified, the eclipse executable launcher tries to identify whether the vm is from Sun or not. If the vm is Sun, then the launcher adds the -XX:MaxPermSize vm argument. On windows, we identify Sun vms using the GetFileVersionInfo API. We read the version information from the java executable (or jvm.dll) and check to see if the company name is "Sun Microsystems".

This worked great and everyone was happy. Fast forward a few years and Oracle acquires Sun. Now starting in Java 6 update 21, the company name in the jre is Oracle. This means the launcher no longer recognizes the vm as being from Sun and the -XX:MaxPermSize vm argument no longer gets applied results once more in Permgen memory problems.

The fix for this change is being tracked in bug 319514.

Friday, May 28, 2010

Opening files in Eclipse from the command line

I ran a query to see all the bugs fixed in the Eclipse Platform in 3.6; it is a long list (4309 and counting). Felipe gets credit for the oldest bug fixed (raised in 2001), but in a close second is bug 4922 (raised only a day later).

This bug is about opening files in eclipse from the command line. Fixing it required a coordinated effort between Platform UI, SWT, and the Equinox launcher. A lot of the credit for what was done goes to Kevin Barnes.

This post is an effort to explain some of the technical details of what is going here.

On the Mac...: On the mac all we do is handle the apple event "kAEOpenDocuments", most of the rest of this post doesn't apply to the mac.

Windows and GTK... Everything below applies to Windows and GTK, though there are some differences in the implementation details.

On Motif... Sorry, this doesn't work on motif.

The Launcher

Everything starts in the eclipse launcher. We added a few new command line options:
  • --launcher.openFile : obvious enough, specifies the file we want to open.
  • --launcher.defaultAction : less obvious, specifies the action to take when the launcher is started without any '-' arguments on the command line. Currently the only support value is "openFile".
  • --launcher.timeout : a timeout value for how long we should spend trying to communicate with an already running eclipse before we give up and just open a new eclipse instance. Default is 60 (seconds).
The first argument is obvious enough, open the specified file in eclipse.
eclipse --launcher.openFile myFile.txt
This is great, but it is a bit much to type on the command line and is not quite enough to make everyone happy. We introduced the "default action" argument. This goes in the eclipse.ini file, the value should be "openFile":
...
-showsplash
org.eclipse.platform
--launcher.defaultAction
openFile
-vmargs
-Xms256m
-Xmx768m
This tells the launcher that if it is called with a command line that only contains arguments that don't start with "-", then those arguments should be treated as if they followed "--launcher.openFile".
eclipse myFile.txt
This is the kind of command line the launcher will receive on windows when you double click a file that is associated with eclipse, or you select files and choose "Open With" or "Send To" Eclipse.

Relative paths will be resolved first against the current working directory, and second against the eclipse program directory.

Talking to SWT

The launcher talks to SWT through the use of a hidden window. The launcher and SWT both need to agree on the name of this window. This allows the launcher to find an already running eclipse and tell it to open the file. Any RCP application will need to ensure they get this right for things to work.

The launcher bases this on its "official name". The official name can be set with the -name argument. If -name is not set, then the official name is derived from the launcher executable, the extension is removed and the first letter is capitalized: rcp.exe becomes Rcp.

SWT bases this on the value set with the Display.setAppName() function. Normally, this is set by the Workbench when it creates the display and the value is the "appName" taken from the product extension point.

Listening to SWT

To take advantage of this, an RCP Application will need to register a listener for the SWT.OpenDocument event. It should register this listener before calling PlatformUI.createAndRunWorkbench so that the listener is in place before the workbench starts running the event loop.

The event loop will start running while the splash screen is still up, so events may arrive before the workbench is ready to actually open an editor for the file. This means that the listener should save the file paths it gets from the OpenDocument events so they can be opened at some later time. WorkbenchAdvisor#eventLoopIdle can be a good place to check for saved open file events.

Implementation details

Here is an overview of the flow of events in the launcher when processing --launcher.openFile on windows.
  1. Get the Official Name. As mentioned above, this is the "-name" argument, or derived from the executable name. For this explanation, we will be using "OfficialName".

  2. Create and lock a mutex named "SWT_Mutex_OfficialName".
    • If multiple files are selected and opened on windows, then a seperate eclipse process will be created for each one. The mutex allows us to ensure only one eclipse instance is actually started.
    • One process will win the race to acquire the mutex, at this point, there will be no eclipse instance running that has the SWT window available. This process will start normally and eventually create the SWT window at which point it will release the mutex.
    • All the other processes wait trying to acquire the mutex, once the original process releases it, they will be able to find the SWT window and post their open file message there.
    • Each process only waits for --launcher.timeout seconds (default 60 seconds) before giving up and just starting its own full eclipse instance.


  3. Find the window named "SWT_Window_OfficialName"
    • If no such window exists, we are the first eclipse instance. In this case, we set a timer to look again later and then proceed with starting eclipse.
    • The timer fires every second for --launcher.timeout seconds.
    • If we don't find the SWT window before the timeout (perhaps it took too long for the workbench to create the display), then we will be unable to open the file.


  4. Send a message to the SWT window
    • Once we've found the SWT window, we create a custom message named "SWT_OPENDOC". We send this message with wParam & lParam specifying a shared memory id.
    • We write to the name of the file to open into shared memory, and when SWT receives the SWT_OPENDOC message, it uses that id to read the shared memory.
    • The launcher has long used shared memory on all platforms for the splash screen, restarts and exit messages.
    • Once SWT reads the file name from shared memory, it posts its own SWT.OpenDocument event.
On GTK, things happen in a similar manner with a few differences:
  1. We use semaphores.
    • Semaphores are not cleaned up automatically if the process exits unexpectedly. So we try to hold the semaphore for as short a time as possible and we install SIGINT and SIGQUIT signal handlers for the time we hold the semaphore.
    • The launcher creates a hidden GTK window named SWT_Window_LauncherOfficalName which is used in the same way as the mutex on windows. This lets us avoid holding the semaphore for an extended time while the first eclipse process starts up.

  2. We use a property instead of a message.
    • The property is named org.eclipse.swt.filePath.message.
    • The value is a colon separate list of file paths to open. Shared memory is not used like it is on windows.