Open topic with navigation

TIBCO Rendezvous® 8.7.0

# Validity of Data Extracted From Messages

To extract data values from a message, programs use a set of get convenience functions. All of these functions 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 function; the get function 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 167: 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 a pointer field, a program declares a typed pointer in program-owned storage, and passes its address to the get function; the get function copies a pointer to the field value into the program’s pointer address. The function 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 168: 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 function would extract updated data from the message.

These semantics apply to all pointer data—arrays, strings, opaque byte sequences, XML data, and submessages.

Figure 169: Updating a Pointer Field

## Do Not Modify Pointer Snapshots

Programs must treat array, string, XML 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 functions 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 functions 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 170: 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 function 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 functions 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 functions to control the proliferation of references.

## See Also

tibrvMsg_MarkReferences()

## Multiple Subscription Snapshots

Rendezvous software also protects the integrity of messages distributed to multiple subscriptions. When a callback function modifies an inbound message (whether detached or not), Rendezvous software still presents the original message content to subsequent callback functions.

Did you find this helpful?

Yes No
Great!
Thanks for taking the time to give us some feedback.
Sorry about that

Why wasn't this helpful? (check all that apply)

Could not find what I was looking for
Instructions confusing or unclear
Instructions did not work

Want to tell us more?

Please select at least one option or provide details about the issue!!

Error occurred while submitting feedback.

Error2 occurred while submitting feedback.

TIBCO Rendezvous®

Copyright © 1997-2023. Cloud Software Group, Inc. All Rights Reserved.