Guievict:  GUI eviction
www.cs.wisc.edu/~zandy/guievict
Copyright (c) 2003 Victor C. Zandy  zandy@cs.wisc.edu

COPYING contains the distribution terms for guievict (LGPL).

Contents:
        1  RELEASE NOTES
        2  INSTALLATION
        3  USING GUIEVICT
        4  LIMITATIONS
        5  CONTACT


1. RELEASE NOTES

Guievict is a system for checkpointing and migrating the GUI of an
X window application.  It is based on a window server extension and
runtime process re-writing; application binaries do not need to be
modified or started in a special way to be used with guievict.

This is the first release of guievict.  Bugs abound; send feedback
to zandy@cs.wisc.edu.

We support guievict for XFree86 4.2.x running on x86 Linux.

A paper describing guievict, entitled "Checkpoints of GUI-based
Applications" (2003 Usenix Annual Technical Conference), is
available at http://www.paradyn.org/papers/#gui


2. INSTALLATION

Because guievict includes a window server extension, compiling and
installing guievict is slightly more complicated than usual.

Guievict comprises three binaries:

evictor       User command line interface to guievict
librt.so      Library injected at run time into X client
libevict.so   X window server extension

To build these binaries from scratch, type 'make' in the
distribution directory.  You must have a copy of the XFree86
sources (available from ftp.xfree86.org) to build libevict.so; set
XSRC in the guievict Makefile to the root of the XFree86 source
tree.  You can build evictor and librt.so without XFree86 sources;
type 'make client'.  For convenience, the source distribution
contains a pre-compiled libevict.so.

The window server must be reconfigured to load libevict.so, an
operation that usually requires root privileges.  There are two
steps:

      1.  Copy libevict.so to the X modules directory
          (/usr/X11R6/lib/modules on Redhat 7.x and higher).
      
      2.  Add the following line to the Module section of XF86Config
          (typically but not always /etc/X11/XF86Config-4):
      
          Load "evict"

Restart your window server to cause the extension to be loaded.
Note that in many configurations it is NOT sufficient to log out
and log back in.  It is best to reboot.

The extension library provides an extension that the window server
recognizes by the name "GUIEVICT".  The command xdpyinfo lists all
extensions in the window server; use it to verify that the
extension is properly loaded.

The evictor and librt.so binaries can be installed anywhere or left
in the source directory.


3. USING GUIEVICT

Suppose you have an X client with process id PID whose GUI you wish
to migrate from its current display to the display named
HOST:SCREEN (in X windows nomenclature).  There are three steps.

    1.  evictor PID hijack [LIBRT-PATHNAME]
        
        This command causes the library librt.so to be injected
        into the client.  It is an initialization step that must be
        performed before any other guievict commands.

        LIBRT-PATHNAME is the full pathname location of librt.so.
        If it is omitted, evictor will look for it in the current
        working directory.

    2.  evictor PID detach

        This command causes the client to detaches its GUI from its
        the window server.  The state of its window session
        (windows, pixmaps, fonts, etc.) are downloaded to the
        client process.  The client blocks awaiting an evictor
        command to re-attach to another window server.

    3.  evictor PID reattach [HOST:SCREEN]

        This command causes the client to re-attach its GUI to the
        window server named HOST:SCREEN.  If the server name is
        omitted, it re-attaches to the window server named in the
        DISPLAY variable in the environment of the CLIENT process
        (not evictor's environment).


4.  LIMITATIONS

Guievict is new software (February 2003).  Not all of the features
we want have been implemented.  Some features are almost ready but
not present in this release.

* Statically-linked executables.  Guievict currently can only
  hijack programs that are dynamically linked.  We have most, but
  not all, of the functionality for hijacking static programs
  programs designed and implemented.  This functionality will
  appear in a release soon.

* Fonts.  As a server-side resource, the fonts used by an X client
  are difficult to checkpoint.  Guievict currently uses an index of
  the fonts available on that server to reverse map font
  identifiers to font names.  It builds this index the first time
  you detach a client from a particular window server.  Depending
  on the environment, the index can take a minute or longer to
  build (it takes 20 seconds on our 700 MHz machine that uses a
  local font server).

  We are still considering our options for eliminating this
  overhead.  The paper gives more details about this issue; we
  welcome thoughts and suggestions.

* Threaded clients.  Guievict is not safe to use in threaded
  clients.  We have seen it work it in practice on some programs,
  but this is just luck.  Thread safety will be addressed in an
  upcoming release.

* Atoms.  Guievict currently does not restore the atoms associated
  with a client's windows, a lacuna with surprisingly mild effects.
  We have this functionality implemented but not debugged.  It will
  appear soon.


5. CONTACT 

Victor Zandy wrote and maintains guievict.  Please report bugs to
zandy@cs.wisc.edu.  Feedback and experience reports are welcome.
The guievict webpage is http://www.cs.wisc.edu/~zandy/guievict.