Auto-refresh overview

Last modified: February 20, 2004

In Eclipse 3.0 an auto-refresh facility was added to the org.eclipse.core.resources plugin. This feature, when enabled, searches the file system for changes that have been made externally, and then automatically refreshes the workspace when new changes are discovered. This document briefly describes the architecture of auto-refresh.

Plug-ins provide change notification to the workspace by hooking into the new refreshProviders extension point. Extensions to this extension point implement subclasses of the following abstract class:

public abstract class RefreshProvider {
	public abstract IRefreshMonitor installMonitor(IResource resource, IRefreshResult result);

When a new project or linked resource is added to the workspace, each installed refresh provider is asked to install a refresh monitor on that location. If for any reason a refresh provider is not able to monitor a given location, it can opt not to return a monitor. If no installed refresh providers are willing to monitor the location (or if no refresh providers are installed), a default refresh provider is implemented by the platform. This default refresh provider uses a naive Java-based polling loop that manually checks for changes in the location at a specified interval (by default, 30 seconds).

Once installed, a monitor is responsible for notifying the workspace when external changes are made to that file system location by invoking methods on the provided callback interface (IRefreshResult). The results are collected by the workspace, and the workspace will synchronize the changed resources in a periodic background job. Note that this hand-off is entirely asynchronous. The monitor is responsible for identifying out of sync resources, and in a separate thread the workspace will process those changes and reconcile them with the workspace tree.

The Eclipse SDK includes refresh provider implementations for both Win32 and Linux platforms. On all other platforms, the default Java-based polling refresh provider is used, unless another plug-in is installed that provides a more efficient platform-specific implementation. On Windows, the refresh provider uses win32 API calls to install a native file system monitor (FindFirstChangeNotificationW in windows.h). File system monitors in win32 are deep, i.e., they report changes on an entire file sub-tree.

On Linux, the refresh provider use a standard Unix utility called FAM (File Alteration Monitor), that is installed by default on most Linux distributions. FAM runs a daemon that uses a native polling loop to detect changes in the file system. Clients can install a monitor on individual directories, and they are provided with a change event queue that they can process at will (either with a blocking dequeue operation or by peaking at the queue in their own polling loop). FAM monitors are shallow, i.e., you need to install separate monitors on each folder of a sub-tree.