When a SockHop program runs, it needs to create processes on (potentially) many different computers. However, before it can do this, there has to be some software already running on each computer, that knows how to accept a SockHop connection and create SockHop nodes. The program that does this is called the SockHop server.
Before you can use a computer as a "slave" SockHop host, you need to (manually) launch the server executable on it. The SockHop server executable is, in fact, the libsockhop.so library file! The BeOS object model allows this one file to do double duty as both shared library and server executable. Once the SockHop server is running on all your computers, SockHop can take care of everything else by itself, and you need not do anything with any of the slave computers after that. Even if the node processes that your program launches on the slave computer crash (which does happen when you are developing new software!), the SockHop server will keep on working. This is because each incoming connection is placed into its own address space, so that a buggy node cannot corrupt the main launcher process.
SockHop server usage format
Currently, the SockHop server must be run from a shell. It takes zero or more arguments to modify its behavior. An example invocation of the server might be:
~/config/lib/libsockhop.so port=5555 password=topsecret debug=1 priority=7 encoding=zlibmedium
The above invocation exercises all the options of the SHDefaultAccessPolicy that is used by default--it runs a server with debug printing on, listening on port 5555, which requires the password "topsecret" from all connecting clients. It spawns threads at priority 7, and encodes outgoing BMessages with "medium" zlib compression. All arguments are optional, so you could also just run the server like this:
~/config/lib/libsockhop.so
This would run the server on the default port (2958), with debug printing
off, no password required, threads at priority 10, no BMessage compression.
Note that this is a security hole roughly equivalent to allowing password-less
telnet and ftp access to your computer, so unless you are on an isolated
network, I highly recommend you specify a password!
Choose where SockHopServer should put its cached files
Generally, nodes that the SockHop server launches will cache their files in the SockHop server's current directory. So it is a good idea to launch the SockHop server from a directory that you have made especially for it, e.g.
mkdir ~/SockHopData
cd ~/SockHopData
~/config/libsockhop.so password=topsecret
The SockHopServer's current directory should be readable and writable, and have enough free space for the files that you will be caching in it. SockHop doesn't provide a mechanism for removing files once they have been cached, so you may want to periodically go through and delete any contents of this directory that you are no longer using. (Note that you only need to do this to recover disk space; a properly written SockHop program will never use out-of-date versions of any cached file, but rather will automatically overwrite them with the current version on each node that uses the file)
You can run multiple SockHop servers at once on a single computer, if
you like, as long as you have each one listen on a different port number.
This can be helpful if you want to separate your debug output into multiple
windows, or if you want to maintain separate cached-file archives, each
in its own directory. But since each SockHop server can accept any
number of simultaneous connections, this isn't ever really necessary.
Using your own custom SHAccessPolicy
object
If the SHDefaultAccessPolicy that the SockHop server isn't sophisticated enough for you, you can write your own access policy as an add-on. Simply subclass the SHAccessPolicy class in your add-on, and then specify your add-on file when you run the SockHop server, as shown below:
~/config/lib/libsockhop.so policy=add-ons/MyPolicyAddOn
If your SHAccessPolicy subclass's name is the same as the add-on's filename, this will be enough to get your add-on policy to be used. If it differs, however, you need to specify the class name as well:
~/config/lib/libsockhop.so policy=add-ons/MyPolicyAddOn class=MyPolicyClass
Any other parameters you put on the command line will be added as string fields to the BMessage which is passed to your class's Instantiate() method. (Indeed, this is how the SHDefaultAccessPolicy gets its parameters from the command line!). So, a command line like this:
~/config/lib/libsockhop.so policy=add-ons/MyPolicyAddOn class=MyPolicyClass color=purple number=42 sad=true
Would instantiate a MyPolicyClass object via it's (BMessage *) constructor, using this BMessage:
what = <unset>
String field "color" = "purple"
String field "number" = "42"
String field "sad" = "true"
String field "class" = "MyPolicyClass"
Flattened field SH_NAME_ADDONSPEC = (flattened SHFileSpec
containing the path "add-ons/MyPolicyAddOn" for the current architecture)
Again, note that all parameters (except the "policy" parameter, which is a special case) are added as Strings only!