      /* $OS_ROOTDIR/include/ostore/client/client.hh */
      os_notification::notify_immediate
      (os_reference&, int kind=0, const char* message=0);

To ensure that subscribers do not receive notifications until the changes are visible in the database, use os_notification::notify_on_commit.

Receiving notifications

An application receives notification using the following functions:

      os_notification::receive (os_notification*&, int timeout=-1);
      os_reference os_notification::get_reference();
      int os_notification::get_kind();
      const char* os_notification::get_string();

Be sure to delete the returned heap-allocated os_notification object when done.

Network Service

When an ObjectStore application uses notifications, it automatically establishes a second network connection to the Cache Manager daemon on the local host. The application uses this connection to receive (and acknowledge the receipt of) incoming notifications from the Cache Manager. (Outgoing notifications are sent to the Server, not the Cache Manager.) See Chapter 1, Overview of Managing ObjectStore, in ObjectStore Management for specific information about defaults.

Notification Errors

The notification APIs do not do complete validation of the arguments passed to them. Invalid arguments can therefore cause segmentation violations or other undefined behavior. See the ObjectStore C++ API Reference, Appendix A, Exception Facility, for information on specific errors.

ObjectStore Utilities for Managing Notification

The ossvrstat utility displays statistics on the number of notifications received and sent by the Server.

The oscmstat utility displays information on notifications queued for clients. This is useful in debugging applications that use notifications.

Detailed descriptions of these and other ObjectStore utilities can be found in Chapter 4, Utilities, in ObjectStore Management.

Notifications Example

The following example illustrates the use of notifications.

#include <ostore/ostore.hh>
#include <iostream.h>
#include <assert.h>
int main(int argc, char** argv) {
      const char* db_name = "notif.db";
      const char* root_name = "Test Object";
      /* can see client name with "ossvrstat -clients <host>" */
      objectstore::set_client_name(argv[0]);
      objectstore::initialize();
      cout << "Opening database "<< db_name << endl;
      os_database* db = os_database::open(db_name,0,0644);
      os_reference ref1 = 0;
      os_reference ref2 = 0;
      os_transaction* txn =
            os_transaction::begin(os_transaction::update);
      os_database_root* root = db->find_root(root_name);
      if (!root) {
            cout << "Creating a couple of ints" << endl;
            root = db->create_root(root_name);
            root->set_value(new (db, os_typespec::get_int(), 2) int[2]);
      } /* end if */
      ref1 = root->get_value(); /* &int[0] */
      ref2 = &((int*)ref1.resolve())[1];  /* &int[1] */
      txn->commit();
      delete txn;
      os_notification* note;
      int iterations = 0;
      os_transaction::begin(os_transaction::read_only);
      /* the Initiator process takes no args on command line */
      if ( argc == 1) {
            cout << "Initiator Starting notifications..." << endl;
            /* subscribe to ref2; */
            os_notification::subscribe(ref2);
            while (iterations < 10) {
                  iterations++;
                  cout << "sending notification, kind = "<< iterations << endl;
                  /* send immediate notification on ref1 with iterations */
                  /* as kind */
                  os_notification::notify_immediate(ref1,iterations);
                  /* now get response into note */
                  os_notification::receive(note);
                  /* make sure note response is on ref2 */
                  os_reference ref = note->get_reference();
                  assert(ref == ref2);
                  /* make sure correct iterations comes back */
                  int kind = note->get_kind();
                  assert(kind == iterations);
                  delete note;  /* avoid memory leak */
                  sleep(2);
            } /* end while */
            /* Tell Responder to exit by sending
            notification on ref1 with kind=0 */
            cout << "sending notification, kind = 0" << endl;
            os_notification::notify_immediate(ref1,0);
            /* Initiator done */
      } /* end if */
      else {
            /*  the Responder process takes any args on command line */
            cout << "Responder Waiting for Notifications" << endl;
            /* subscribe to ref1 */
            os_notification::subscribe(ref1);
            while(1) {
                  /* receive notification for ref1 into note */
                  os_notification::receive(note);
                  /* see what kind it is */
                  int kind = note->get_kind();
                  cout << "received notification, kind = "<< kind << endl;
                  /* if kind is 0, exit */
                  if (kind == 0)
                  break;  /* Responder done */
                  /* make sure notification is about ref1 */
                  os_reference ref = note->get_reference();
                  assert(ref == ref1);
                  delete note; /* avoid memory leak */
                  /* send notification on ref2 with kind */
                  os_notification::notify_immediate(ref2,kind);
            } /* end while */
      } /* end if */
      return 0;
}

[previous] [next]

Updated: 03/31/98 16:58:45