VkRunOnce2(3x)
VkRunOnce2 - Allow an application to have only a single instance
As shipped in IRIX 6.5.30. Unchanged since IRIX 6.5.
NAME VkRunOnce2 - 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 DESCRIPTION VkRunOnce2 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. FUNCTION DESCRIPTIONS VkRunOnce2 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); 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() { 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 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 ALSO VkApp(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