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);