Libunique for OpenSolaris [LSARC/2009/142 FastTrack timeout 03/10/2009]

Sun Mar 1 23:19:37 PST 2009

Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
This information is Copyright 2009 Sun Microsystems
1. Introduction
    1.1. Project/Component Working Name:
	 Libunique for OpenSolaris
    1.2. Name of Document Author/Supplier:
	 Author:  Halton Huo
    1.3  Date of This Document:
	01 March, 2009
4. Technical Description

1. Introduction
   1.1. Project/Component Working Name:
        LibUnique

   1.2. Name of Document Author/Supplier:
        Halton Huo

   1.3. Date of This Document:
        02/23/09

   1.4. Name of Major Document Customer(s)/Consumer(s):

      1.4.1. The PAC or CPT you expect to review your project:
             Solaris PAC

      1.4.2. The ARC(s) you expect to review your project:
             LSARC

      1.4.3. The Director/VP who is "Sponsoring" this project:
             Robert O'Dea

      1.4.4. The name of your business unit:
             Software - OPG

   1.5. Email Aliases:

      1.5.1. Responsible Manager:
             harry.lu at sun.com

      1.5.2. Responsible Engineer:
             halton.huo at sun.com

      1.5.3. Marketing Manager:
             glynn.foster at sun.com

      1.5.4. Interest List:
             desktop-discuss at opensolaris.org

2. Project Summary
   2.1. Project Description:

        LibUnique is a library for writing a single instance application.
        If you launch a single instance application twice, the second instance
        will exit quietly or will send a message to the running instance.

        LibUnique makes it easy to write these kind of applications, by
        providing a base class, taking care of all the IPC machinery needed
        to send messages to a running instance, and and also handling startup
        notification.

        LibUnique aims to obsolete very similar code (for example, the
        BaconMessageConnection interface) that has been copied into many
        projects and replace it with standard LibUnique library interfaces.

4. Technical Description:
    4.1. Details:

         LibUnique offers the following features:
         * simple API, easy to subclass
         * custom commands
         * bidirectional communication channel
         * signal based
         * commodity API for sending raw data, plain text and URI lists
         * multiple backends (changeable at runtime)

         LibUnique supports two IPC backends: bacon and dbus. The default
         backend is dbus. User can override the default backend by setting
         the UNIQUE_BACKEND environment variable with the name of the
         desired backend.

         When dbus is used, the messages are transmitted through private 
         channel:
                 connection=DBUS_SESSION_BUS
                 name=org.mydomain.YourApplication
                 path=/Factory
                 interface=org.gtk.UniqueApp

         When bacon is used, libUnique uses PF_UNIX family socket to allow
         communications between processes on the same machine. The socket file
         is created as
         /var/tmp/unique/org.gnome.YourApplication.token.process-id.

         In this example, the string "org.gnome.YourApplication" is passed
         to applications which use libunique to create the UniqueApp instance.

         This string must be unique for different applications. Otherwise, the
         second application can not be started. Assume nautilus and
         vino-preferences use same string "Oh.God". If nautilus is running
         (it should be always running with session), unique_app_is_running()
         returns TRUE, it will cause vino-preferences will not be started.

    4.2. Interfaces:

      Exported Interfaces                    Classification    Comments
      -----------------------------------    --------------    -----------
      SUNWlibunique                          Uncommitted       Package name
      SUNWlibunique-devel                    Uncommitted       Package name
      /usr/lib/pkgconfig/unique-1.0.pc       Uncommitted       pkg-config file
      /usr/lib/libunique-1.0.so.0            Volatile          C library
      /usr/include/unique-1.0/unique         Volatile          header files
      /usr/share/gtk-doc/html/unique         Volatile          gtk-doc files

      Imported Interfaces                    Classification    Comments
      -----------------------                ---------------   ----------
      D-Bus & dbus-glib                      Volatile          LSARC 2006/368
      GNOME Committed Platform Libraries     Committed         LSARC 2007/520

    4.3. Doc Impact:
	 Man page for libunique-1.0.3 is added

    4.7. Admin/Config Impact:
         None.

    4.8. HA Impact:
         None.

    4.9. I18N/L10N Impact:
         The JDS team and the G11N team are working together to evaluate and
         provide I18N/L10N support.

    4.10. Packaging & Delivery:
      Adds new packages:
      SUNWlibunique (base package)                - base package for libraries
      SUNWlibunique-devel (development package)   - development package for 
                                                    header and documents
      Packages will only go into SUNWCall and SUNWCXall clusters.

    4.11. Security Impact:
          When dbus is used as backend, the D-Bus communication is only allowed
          by processes started by the same user, so other users can not
          interact via D-Bus.

          When bacon is used as backend, the PF_UNIX socket files under
          /var/tmp/unique/ is owned by user:other with 700 permissions to
          prevent tampering.

    4.12. Dependencies:
          LSARC 2006/368 D-Bus & dbus-glib

5. Reference Documents:

      [1] Related ARC Cases:
          LSARC 2006/368: D-Bus & dbus-glib
          LSARC 2007/520: GNOME Committed Platform Libraries

      [2] Project homepage: 
          http://live.gnome.org/LibUnique

6. Resources and Schedule
    6.4. Steering Committee requested information
   	6.4.1. Consolidation C-team Name:
		Desktop
    6.5. ARC review type: FastTrack
    6.6. ARC Exposure: open