C H A P T E R 1 2
Special-Purpose Objects for Data Storage and Retrieval
12-2
About Special-Purpose Storage Objects
Virtual Binary Objects
12
The size of any NewtonScript object is limited by the amount of memory available
in the NewtonScript heap. As a result, you cannot create binary objects larger than
the amount of available NewtonScript heap space. For similar reasons, the amount
of data that can be stored in a single soup entry is limited as well. (See "Saving
Frames as Soup Entries" beginning on page 11-58 for details.) You can use virtual
binary objects to work around these restrictions.
in the NewtonScript heap. As a result, you cannot create binary objects larger than
the amount of available NewtonScript heap space. For similar reasons, the amount
of data that can be stored in a single soup entry is limited as well. (See "Saving
Frames as Soup Entries" beginning on page 11-58 for details.) You can use virtual
binary objects to work around these restrictions.
A virtual binary object or VBO is a special kind of object that is useful for
holding binary data larger than the available space in the NewtonScript heap. VBOs
can be used to store large amounts of raw binary data, such as large bitmaps, the
samples of large digitized sounds, fax data, packages, or application-specific binary
data. A package is actually a special kind of virtual binary object; however, a package
is read-only and is created in a slightly different manner than a normal VBO.
holding binary data larger than the available space in the NewtonScript heap. VBOs
can be used to store large amounts of raw binary data, such as large bitmaps, the
samples of large digitized sounds, fax data, packages, or application-specific binary
data. A package is actually a special kind of virtual binary object; however, a package
is read-only and is created in a slightly different manner than a normal VBO.
In the following ways, VBOs are like normal NewtonScript binary objects:
The VBO is not persistent until it is written to a soup. As with any soup entry data,
if a VBO in a soup entry is modified, the changes are not persistent until the
cached entry frame is written back to the soup. If a soup entry containing a VBO
is moved to another store, the binary data associated with the VBO is moved to
that store as well. For a discussion of the soup entry cache, see "Entries" on
page 11-17.
if a VBO in a soup entry is modified, the changes are not persistent until the
cached entry frame is written back to the soup. If a soup entry containing a VBO
is moved to another store, the binary data associated with the VBO is moved to
that store as well. For a discussion of the soup entry cache, see "Entries" on
page 11-17.
The space used by the VBO is made available for garbage collection when there
are no more references to the VBO.
are no more references to the VBO.
Binary data--including VBO data--is not shared between soup entries, even
when their respective soups reside on the same store. As a result, you may need
to consider space issues when moving or duplicating entries that hold VBO data.
when their respective soups reside on the same store. As a result, you may need
to consider space issues when moving or duplicating entries that hold VBO data.
VBOs are different from normal NewtonScript binary objects in the following ways:
VBO data does not reside in the NewtonScript heap--it resides in store memory.
Store memory for VBO data is not allocated until it is needed to write data. "Using
Virtual Binary Objects" on page 12-8 discusses this important point in detail.
Virtual Binary Objects" on page 12-8 discusses this important point in detail.
You cannot use a value stored in a virtual binary object as a soup index key.
VBOs can be created in compressed or uncompressed form. If the VBO is
compressed, the system compresses and decompresses its associated binary data
on demand. The fact that a VBO is compressed is normally transparent to your
code; however, the time required to compress and uncompress VBO data may
affect performance.
compressed, the system compresses and decompresses its associated binary data
on demand. The fact that a VBO is compressed is normally transparent to your
code; however, the time required to compress and uncompress VBO data may
affect performance.
When passed a reference to a VBO residing on a store that is unavailable,
methods that write VBO data throw exceptions rather than displaying the
"Newton still needs the card" alert.
methods that write VBO data throw exceptions rather than displaying the
"Newton still needs the card" alert.