ObjectStore C++ API Reference

os_subscription

Objects of class os_subscription are created by users in order to perform subscription and unsubscription operations. Note that you do not always have to create os_subscription objects in order to subscribe or unsubscribe. You can accomplish a single subscription or unsubscription by passing an os_database, os_segment, os_object_cluster, or address range directly to os_notification::subscribe() or os_notification::unsubscribe().

The main reason to manipulate os_subscription objects directly is to pass an array of them to os_notification::subscribe. There are overloadings of os_notification::subscribe that take the same sets of arguments as os_subscription constructors. Use these if you want to subscribe only to a single notification address. You can call these directly and completely bypass the use of os_subscriptions.

The reason you might want to pass an array of os_subscription to os_notification::subscribe is that it is much more efficient to call os_notification::subscribe once with an array than to call it separately for each subscription when there are multiple subscriptions to register.

Each os_subscription object represents an address range in an ObjectStore database. There are four constructors that allow creation of subscriptions covering an entire database, an entire segment, an entire object cluster, or a specific location range:

os_subscription::os_subscription()

There is a default constructor, os_subscription();, that creates an uninitialized subscription.

os_subscription(const os_database *);

This constructor is used to create a subscription to an entire database.

os_subscription(const os_segment *);

This constructor is used to create a subscription to a segment.

os_subscription(const os_object_cluster *);

This constructor is used to create a subscription to an object cluster.

os_subscription(
const os_reference &, 
os_int32 n_bytes = 1
);

os_subscription::assign()

The default constructor is most useful when you are allocating an array of subscriptions. Each os_subscription in the array will initially be uninitialized. Each array element can then be initialized using the assign or operator= member functions:

      void assign(const os_database *);
      void assign(const os_segment *);
      void assign(const os_object_cluster *);
      void assign(const os_reference &, os_int32 n_bytes = 1);
      os_subscription &operator=(const os_database *db);
      os_subscription &operator=(const os_segment *seg);
      os_subscription &operator=(const os_object_cluster *clus);
      os_subscription &operator=(const os_reference &ref);

Objects of type os_subscription can be reassigned in this fashion as many times as desired. Note that because operator= only allows a single argument, you must use the final form of assign if you want to specify n_bytes > 1.

When passing database locations to os_subscription member functions, you do not need to explicitly convert to os_reference. You can pass pointers or os_Reference<X>; these are converted by C++ automatically.

os_subscription::get_database()

os_database *get_database();

The only accessor for os_subscription returns the database associated with the subscription. An uninitialized os_subscription has a null (0) database.

Subscribe and unsubscribe nonstatic member functions are provided as shortcuts for calling os_notification::subscribe() and os_notification::unsubscribe(). They are

void subscribe();
void unsubscribe();

Further discussion

See os_namespace for further discussion about notification.

[previous] [next]

Updated: 03/31/98 17:25:09