wx.SingleInstanceChecker

wx.SingleInstanceChecker class allows checking that only a single instance of a program is running.

To do it, you should create an object of this class. As long as this object is alive, calls to wx.SingleInstanceChecker.IsAnotherRunning from other processes will return True.

As the object should have the life span as big as possible, it makes sense to create it either as a global or in wx.App.OnInit . For example:

def OnInit(self):

    self.name = "SingleApp-%s" % wx.GetUserId()
    self.instance = wx.SingleInstanceChecker(self.name)

    if self.instance.IsAnotherRunning():
        wx.MessageBox("Another instance is running", "ERROR")
        return False

    frame = SingleAppFrame(None, "SingleApp")
    frame.Show()
    return True

Note that by default wx.SingleInstanceChecker.CreateDefault is used to create the checker meaning that it will be initialized differently for different users and thus will allow different users to run the application concurrently which is usually the required behaviour. However if only a single instance of a program should be running system-wide, you need to call Create with a custom name which does not include wx.GetUserId .

This class is implemented for Win32 and Unix platforms (supporting fcntl() system call, but almost all of modern Unix systems do) only.

Class Hierarchy

Inheritance diagram for class SingleInstanceChecker:

Methods Summary

__init__	Default constructor.
Create	Initialize the object if it had been created using the default constructor.
CreateDefault	Calls Create with default name.
IsAnotherRunning	Returns True if another copy of this program is already running and False otherwise.

Class API

class wx.SingleInstanceChecker(object)

Possible constructors:

SingleInstanceChecker() -> None

SingleInstanceChecker(name, path='') -> None

SingleInstanceChecker class allows checking that only a single instance of a program is running.

Methods

__init__(self, *args, **kw)

Overloaded Implementations:

---

__init__ (self)

Default constructor.

You may call Create after using it or directly call IsAnotherRunning in which case CreateDefault will be implicitly used.

Return type:

None

---

__init__ (self, name, path=’’)

Constructor calling Create .

This constructor does exactly the same thing as Create but doesn’t allow to check for errors.

Parameters:

• name (string)

• path (string)

Return type:

None

---

---

Create(self, name, path='')

Initialize the object if it had been created using the default constructor.

Note that you can’t call Create more than once, so calling it if the non default constructor had been used is an error.

Parameters:

• name (string) – Must be given and be as unique as possible. It is used as the mutex name under Win32 and the lock file name under Unix. wx.App.GetAppName and wx.GetUserId are commonly used to construct this parameter.

• path (string) – The path is optional and is ignored under Win32 and used as the directory to create the lock file in under Unix (default is wx.GetHomeDir ).

Return type:

bool

Returns:

Returns False if initialization failed, it doesn’t mean that another instance is running – IsAnotherRunning to check for it.

Note

One of possible reasons while Create may fail on Unix is that the lock file used for checking already exists but was not created by the user. Therefore applications shouldn’t treat failure of this function as fatal condition, because doing so would open them to the possibility of a Denial of Service attack. Instead, they should alert the user about the problem and offer to continue execution without checking if another instance is running.

---

CreateDefault(self)

Calls Create with default name.

This method simply calls Create with a string composed of wx.App.GetAppName and wx.GetUserId .

Because this method uses wx.App.GetAppName , it may only be called after the global application was constructed.

Return type:

bool

Added in version 2.9.1.

---

IsAnotherRunning(self)

Returns True if another copy of this program is already running and False otherwise.

Notice that if the object was created using the default constructor Create hadn’t been called before this method, it will call CreateDefault automatically.

Return type:

bool