VkRunOnce2(3x)VkRunOnce2(3x)NAMEVkRunOnce2 - Allow an application to have only a single instance
INHERITS FROM
VkComponent : VkCallbackObject
HEADER FILE
#include <Vk/VkRunOnce2.h>
PUBLIC PROTOCOL SUMMARY
Constructor/Destructor
VkRunOnce2(VkNameList *args, Boolean per_host);
~VkRunOnce2();
Retrieving Arguments
int numArgs();
char *arg(int index);
Callbacks
const char *const invokedCallback;
CLASS DESCRIPTIONVkRunOnce2 is a subtle variation on VkRunOnce. Both classes allow
applications to specify that only a single instance of the application
can be run on any system at any one time. This is useful when
implementing applications that are meant to provide a system-wide service
for multiple applications. For example, an audio control program that
controls the volume an other parameters on a system should not normally
need to have multiple instantiations. However, various programs or
scripts might wish to launch the application, and have no way to know if
the program is already running.
Using VkRunOnce2, such programs can simply be run as many times as
desired. Only the first run will actually display the program.
Subsequent runs will notify the running instance, possibly passing some
arguments. The running instance will raise itself, and respond to any
arguments provided. The second instance of the application will simply
exit.
The primary difference between VkRunOnce2 and VkRunOnce is that
VkRunOnce2 is more flexible, and can be invoked before instantiating
VkApp. This can be more efficient, in that an application can attempt to
notify the currently running process before it starts the possibly time-
consuming initialization process represented by VkApp and application-
defined subclasses. If this application is the first to be launched,
however, this approach is less efficient, since it opens the X display
twice.
Page 1
VkRunOnce2(3x)VkRunOnce2(3x)FUNCTION DESCRIPTIONSVkRunOnce2
VkRunOnce2(Boolean autoRaise)
VkRunOnce2(VkNameList *args,
Boolean per_host);
VkRunOnce2(char **args, int numArgs,
Boolean per_host, Boolean autoRaise);
Initialize a VkRunOnce2 object. If this is the only current instance
of this program running on the system, this constructor establishes
this application as the sole runnable instance. Normally, "running
on this system" is defined to mean an application whose X DISPLAY is
set to the current display device. If per_host is TRUE, multiple
instances are allowed on any given display, so long as each instance
is running on a different host. Arguments may be passed as either a
character array, or a VkNameList object. If autoRaise is True, the
running application is raised when another instance is started.
If this is the second time an application is run, and args is
provided on either form, the VkRunOnce2 constructor makes contact
with the running instance, passing it any arguments supplied in the
args parameter. The constructor then causes the application to exit
by calling VkApp::terminate().
If the first form of the VkRunOnce2 constructor is used, this process
does not occur. The process of contacting running processes and
establishing this process as the running process must be initiated
manually by calling notifyOthers() and takeCharge().
~VkRunOnce2
~VkRunOnce2();
If the VkRunOnce2 object is deleted, and this application is the
current single instance of this application, multiple instances of
this program are then allowed to run.
className
virtual const char* className();
The class name of this class is "VkRunOnce2".
notifyOthers
void notifyOthers(VkNameList *,
Boolean per_host = FALSE,
const char *name = NULL);
void notifyOthers(char **args, int numArgs
Boolean per_host = FALSE,
const char *name = NULL);
Page 2
VkRunOnce2(3x)VkRunOnce2(3x)
This function is invoked to notify other running instances of this
application that a new one has started. Arguments provided to this
function are passed to the currently running instance. This function
never returns, the calling application exits after notifying the
running instance.
takeCharge
void takeCharge();
This function establishes the calling application as the running
instance. It would typically be called after calling notifyOthers().
EXAMPLES
The following program displays a string in a window. After the first
instance, subsequent instances of the program pass the first command line
argument to the running instance, to be displayed as a string in the
application's window.
#include <Vk/VkApp.h>
#include <Vk/VkRunOnce2.h>
#include <Vk/VkNameList.h>
#include <Vk/VkSimpleWindow.h>
#include <Xm/Label.h>
// Define a top-level window class
class RunOnceWindow: public VkSimpleWindow {
protected:
Widget _label;
public:
RunOnceWindow ( const char *name ) :
VkSimpleWindow ( name )
{
_label = XmCreateLabel ( mainWindowWidget(),
"first instance",
NULL, 0 );
addView(_label);
}
~RunOnceWindow();
void update(VkComponent *comp, XtPointer, XtPointer);
virtual const char* className() {
Page 3
VkRunOnce2(3x)VkRunOnce2(3x)
return "RunOnceWindow";
}
};
RunOnceWindow::~RunOnceWindow()
{
// Empty
}
void RunOnceWindow::update(VkComponent *comp,
void*,
void*)
{
// Just retrieve the arguments, Use the first string
// as a new label for the widget and the second
// as a color.
VkRunOnce2 *obj = (VkRunOnce2*) comp;
if(obj->numArgs() > 0)
{
XtVaSetValues(_label,
XtVaTypedArg,
XmNlabelString, XmRString,
obj->arg(0),
strlen(obj->arg(0) ) + 1,
NULL);
}
}
// Main driver. Instantiate a VkApp and a top-level
// window, "show" the window and then "run" the
// application. The VkRunOnce2 object prevents
// multiple instances of the application.
void main ( int argc, char **argv )
{
// Instantiate VkRunOnce and notify other
// running instances, if any
VkRunOnce2 *runOnce = new VkRunOnce2();
ro->notifyOthers(argv, argc);
// If we get here, this is the first running instance
// so proceed with creating a VkApp object
VkApp *app = new VkApp("RunOnce", &argc, argv);
// Now, establish this process as the first running
// instance of this application
Page 4
VkRunOnce2(3x)VkRunOnce2(3x)
ro->takeCharge();
// Create a window
RunOnceWindow *win = new RunOnceWindow("hello");
// Register a callback for running applications
// to receive if anyone attempts to run this
// application again.
VkAddCallbackMethod(VkRunOnce2::invokedCallback, runOnce,
win, RunOnceWindow::update, NULL);
win->show();
app->run();
}
INHERITED MEMBER FUNCTIONS
Inherited from VkComponent
installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(),
setDefaultResources(), getResources(), manage(), unmanage(),
baseWidget(), okToQuit(), _name, _baseWidget, _w, deleteCallback
Inherited from VkCallbackObject
callCallbacks(), addCallback(), removeCallback(),
removeAllCallbacks()SEE ALSOVkApp(3x), VkRunOnce
ViewKit Programmer's Guide
The X Window System, DEC Press, Bob Sheifler and Jim Gettys
The X Window System Toolkit, DEC Press, Paul Asente and Ralph Swick
The OSF/Motif Programmers Reference, Prentice Hall, OSF
Page 5
