How to use a Mutex (Part 2)

Now that we know how to determine whether another instance of the application is running on the same machine, let's extend the idea a bit further to make it useful. Let's create a way to pass information back and forth between multiple instances of the application.

To do so, we're going to use something called an IPC connection, or Inter-Process Communication. This is essentially a socket that will only communicate with other sockets residing on the same machine. Because all the information is flowing between processes on the same machine, the data transfer is much faster than with a regular socket, and you don't have to worry about firewalls, NAT devices or other networking hardships.

REALbasic has IPC functionality built-in (since 5.x, I believe), so we'll be discussing how to use the IPCSocket class.

IPCSockets on OS X and Linux are based off of a virtual file that lives on the user's file system. Because of this, you use a path instead of an address and port when working with IPC. So the first thing we need to do is pick a path for our socket. This path is generally located in the /tmp/ directory, so we'll use /tmp/MySpiffyApplication as the path for our IPCSocket. Note that on Windows, the path is used to identify the IPCSocket as well, but there's no physical file that resides on the user's file system.

Everything else about an IPCSocket behaves exactly the same as a TCPSocket. One socket does a Listen, and another one does a Connect. Once the connection is established, then both sockets get a Connected event and are able to transfer data between each other using Write, Read and ReadAll.

So let's define a simple protocol to use so that a second instance of an application can tell the initial instance to open a particular file. Here's some rough steps we need to take:
When the app launches, check to see if it's the only instance. If it is the only instance, then make our IPCSocket listen for connections. If it's not the only instance, then make our IPCSocket connect. Once the connection is established, send the file's absolute path over and wait. If we receive data in our IPCSocket, assume it's absolute path data and open that file. Once we've received data, we'll terminate the connection.

So here's what the App class will look like. In the Open event, we construct the objects that we need, and in the OpenDocument event, we send the file name across. We're also going to handle the NewDocument event so that we can bring the other instance to the front before quitting.
[rbcode]
Sub App.Open()
mMutex = new Mutex( "My Spiffy Application" )
mIPCSocketSubclass = new MySpiffyIPCSocket

if mMutex.TryEnter then
mIPCSocketSubclass.Listen
else
mIPCSocketSubclass.Connect
// Force the connection to occur
while not mIPCSocketSubclass.IsConnected and mIPCSocketSubclass.LastErrorCode = 0
mIPCSocketSubclass.Poll
wend
end if
End Sub

Sub App.OpenDocument( f as FolderItem )
if mIPCSocketSubclass.IsConnected and not mMutex.TryEnter then
mIPCSocketSubclass.Write( f.AbsolutePath )
end if
End Sub

Sub App.NewDocument()
if mIPCSocketSubclass.IsConnected and not mMutex.TryEnter then
mIPCSocketSubclass.Write( "?front?" )
end if
End Sub
[/rbcode]
Now we'll take a look at how the MySpiffyIPCSocket class works. First, we'll give it a constructor method, which is responsible for setting the path for the socket. Then we'll implement the DataAvailable event so that we can utilize our protocol.
[rbcode]
Class MySpiffyIPCSocket Inherits IPCSocket
Private Dim mQuitter as Boolean

Sub Constructor()
me.Path = "/tmp/MySpiffyApplication"
End Sub

Sub Error() Handles Event
// We want to go ahead and re-listen here.
if not mQuitter then
me.Listen
end if
End Sub

Sub DataAvailable() Handles Event
dim data as String = me.ReadAll
if data = "?quit?" then
mQuitter = true
Quit
elseif data = "?front?" then
FindTheMainWindow().Show
me.Write( "?quit?" )
else
App.OpenDocument( GetFolderItem( data ) )
me.Write( "?quit?" )
end if
End Sub
End Class
[/rbcode]
As you can see, our protocol is quite stupidly simple. If we get data that says "?quit?" then we'll terminate. Otherwise, the data is treated as a file path. If we get a file path, then we construct a FolderItem from it and pass it to the Application.OpenDocument method (which then passes it along to the OpenDocument event), then we tell the remote application to quit. Furthermore, if we get a "?front?" message, then we'll bring the main application window to the front and tell the other application to quit as well. You'll notice that we re-listen once the connection is terminated. If we don't do this, then the next time the user tries to launch a second copy of the app, there's no IPCSocket listening for the connection. So we flag which end is the quitting end, and if it's a quitter, we just ignore the Error event.

This code is by no means ideal, I might add. There's no error checking, the protocol isn't robust, and I don't think it encapsulates (in the OO sense) the problem we're trying to solve very well. However, I feel that it does show one possible solution to the problem -- elegance, in this case, is left up to the reader. I've uploaded the example described here. You can see how things happen by checking the system's debug string viewer (such as DebugView on Windows, or the Console on the Mac) since I added logging code to make it spit out what happens at each step.

Enjoy!