Validity of Data Extracted From Message Fields
To extract data values from the fields of a message, programs use a set of get convenience methods. All of these methods extract a snapshot of the message data—that is, the data value as it exists at a particular time. If the program later modifies the message by removing or updating the field, the snapshot remains unchanged.
Rendezvous messages implement snapshot semantics using two separate strategies for scalar data and pointer data.
Scalar Snapshot
To extract the value of a scalar field, a program declares a scalar in program-owned storage, and passes its address to the get method; the get method copies a snapshot of the scalar field value from the message into program storage.
The program can modify its snapshot at any time without affecting the original message. The program can update or delete the message field at any time without affecting the snapshot copy.
Figure 207: Extracting a Scalar Field
Pointer Snapshot
Pointer data is a broad category, which includes arrays, strings, opaque byte sequences, XML data, and submessages.
To extract the value of an array, string, XML, or opaque field, a program declares a typed pointer variable in program-owned storage, and passes its reference to the get method; the get method copies a pointer to the field value into the program’s variable. The method does not copy data into program-owned storage; the data still resides in storage associated with the message. Nonetheless, Rendezvous software protects the integrity of snapshot pointer data from subsequent changes to the message field.
Figure 208: Extracting a Pointer Field
(Schematic diagrams in this section illustrate the general principles of snapshot semantics as they apply to pointer data of message fields. However, these diagrams do not accurately reflect the storage allocation and geometry of messages, nor do they reflect the underlying implementation of snapshots.)
Rendezvous Protects Pointer Snapshots from Changes to the Message
If the program removes the field from the message, then Rendezvous software protects the integrity of the snapshot data by retaining it in storage associated with the message; the program’s pointer to the snapshot data remains valid until the message is destroyed, even though the data is no longer accessible through the message.
If the program updates the message field (see Updating a Pointer Field), then Rendezvous software protects the integrity of the snapshot data by retaining it in storage associated with the message; the program’s pointer to the snapshot data remains valid until the message is destroyed, and the program’s view of the snapshot data remains unchanged—even though the get method would extract updated data from the message.
These semantics apply to all pointer data—arrays, strings, opaque byte sequences, XML data, and submessages.
Figure 209: Updating a Pointer Field
Do Not Modify Pointer Snapshots
Programs must treat array, string, XML data and opaque pointer data as read-only snapshots, and must not modify the data to which those pointers refer. For example, it is illegal for programs to change any element in a snapshot array; it is illegal for programs to change any byte in snapshot strings, XML data or opaque byte sequences.
Although Rendezvous software does not enforce this restriction, violating this rule is dangerous, and can result in erroneous program behavior. Do not attempt to modify the elements of an array snapshot, nor the bytes of a string, XML data or opaque snapshot.
Updating a Pointer Field illustrates the correct way to modify the value of pointer data within a message field. Instead of directly modifying storage associated with the message, supply the new value through an update call, which replaces the whole value of the field. (Even after updating or removing the field, it is still illegal to modify the snapshot.)
Although superseded snapshot data remains in storage associated with the message, it is not included when sending the message, nor when accessing message fields.
Rendezvous Protects the Message from Changes to Submessage Snapshots
In contrast to other pointer data, programs may legally modify snapshot submessages (since a submessage is also a message in its own right). Field modification methods apply equally to ordinary messages and to submessage snapshots extracted using get calls.
Moreover, modifying a snapshot submessage does not affect the original field in the parent message. Field modification methods protect the integrity of the parent message when updating or removing a field in a submessage snapshot, or when adding a new field to the submessage snapshot.
Updating a Submessage Field illustrates this protection for parent messages. After updating a field in a snapshot submessage, subsequent get calls extract a pristine copy of the submessage from the field of the parent message, creating a second snapshot. Meanwhile, the modified snapshot submessage remains in storage owned by the parent message; it remains valid until the parent message is destroyed. (However, if the program detaches the snapshot submessage, it remains valid until the program explicitly destroys the submessage.)
Figure 210: Updating a Submessage Field
Deleting Snapshot References
Ordinarily, snapshot references remain part of the message until the program destroys the message. However, in rare situations snapshots can accumulate within a program, causing unbounded memory growth.
For example, consider the result of a program that calls a method repeatedly on the same message, where each call creates a new snapshot within the storage associated with that message. Message storage grows, and destroying the message is the only way to free that storage.
A pair of methods give programs explicit control over snapshot references, so you can avoid such situations:
| • | TibrvMsg::markReferences() |
| • | TibrvMsg::clearReferences() |
When a program repeatedly extracts snapshot references data and does not destroy the parent messages, consider using these methods to control the proliferation of references.
See Also
Multiple Subscription Snapshots
Rendezvous software also protects the integrity of messages distributed to multiple subscriptions. When a callback method modifies an inbound message (whether detached or not), Rendezvous software still presents the original message content to subsequent callback methods.