Basic Examples of how to use SH_NAME_WHENDONE
Example 1. How to be sure your tree is entirely set up.
Since SockHop is asynchonous, the setting up of your node tree goes on
in parallel with your code--that is, you never "block" while things are
happening. But sometimes you still need to know when SockHop has
finished; for example, you might like to know when all the connection you
requested have been established, so that you can start sending BMessages
to the nodes that it created. For simple networks, you could use
SH_NAME_ONSUCCESS and SH_NAME_ONFAILURE
to get BMessages back for each connection, and then examine or count the
BMessages to track the node tree's status. SH_NAME_WHENDONE provides
a simpler mechanism, however. In this example, we will will set up
a three-node network, and receive a BMessage when all three nodes are ready,
or have failed to be created.
BMessage setup(SH_COMMAND_ADDCOMPONENTS);
setup.AddString(SH_NAME_TO, "/");
// Tell the root node to add three children.
setup.AddFlat(SH_NAME_CHILDREN, &SHNodeSpec("node_1",
"beos1.sockhop.com"));
setup.AddFlat(SH_NAME_CHILDREN, &SHNodeSpec("node_2",
"beos2.sockhop.com"));
setup.AddFlat(SH_NAME_CHILDREN, &SHNodeSpec("node_3",
"beos3.sockhop.com"));
// Now the interesting part...
BMessage whenDone('Done');
whenDone.AddString(SH_NAME_TO, "/..");
setup.AddMessage(SH_NAME_WHENDONE, &whenDone);
root->PostMessage(&setup);
// Now, when your target BLooper receives
a 'Done' BMessage, it knows that all setup
// activity in the node tree has completed.
It is guaranteed that you will always
// receive exactly one copy of your WHENDONE
BMessage, even under dire circumstances.
// (for example, even if all of the other
computers in your node tree were to explode!)
// Note that the SH_NAME_WHENDONE field
is more useful when used in conjunction with
// the SH_NAME_ONFAILURE field.
You can use SH_NAME_ONFAILURE to invoke error handling
// code, and SH_NAME_WHENDONE to let your
main process know when it's okay to proceed
// past the setup stage.
Example 2. Use SH_NODE_WHENDONE to create some TestWorkers, and
then send them a BMessage. A problem with SHWorkers occurs when you
send BMessages to them immediately after sending out the SH_COMMAND_ADDCOMPONENTS
BMessage that creats them. The problem is that sometimes the add-on
executables for the SHWorkers don't exist on the target nodes yet, and
the target nodes have to request them from their ancestors in the node
tree. Since the nodes continue to process other BMessages while waiting
for the add-on files to be sent to them, your BMessages might be processed
on the node before their target SHWorkers exist yet, in which case the
BMessages would be dropped. One way to avoid this problem is to use
SH_NAME_WHENDONE to delay sending of the BMessages till all SHWorkers have
been created:
// A BMessage that will set up one TestWorker
on every node that receives it...
BMessage setup(SH_COMMAND_ADDCOMPONENTS);
setup.AddString(SH_NAME_TO, "/*");
// goes to ALL nodes directly under the root node!
TestWorker worker;
BMessage archive;
worker.Archive(&archive);
setup.AddMessage(SH_NAME_WORKERS, &archive);
// This BMessage will be posted EXACTLY
once. It will be posted from the same place
// where (setup) entered the SockHop node
tree (the root node, in this case). It won't
// be posted until ALL TestWorkers have
been instantiated (or failed to instantiate, either way)
BMessage whenDone('DoIt');
whenDone.AddString(SH_NAME_TO, "/*");
// It will go to the same places the setup message went to
setup.AddMessage(SH_NAME_ONSUCCESS, &whenDone);
root->PostMessage(&setup);