C H A P T E R 1 1
Data Storage and Retrieval
Using Newton Data Storage Objects
method copies the cached entry--not the
original soup entry--into the destination soup.
Sharing Entry Data
Shared soups and shared entries need to be in a well-documented format to allow
other applications to use them. For an example of how to document the structure of
your soup entries, refer to Chapter 19, "Built-in Applications and System Data."
There you will see descriptions of the soups used by the built-in applications on
Newton devices produced by Apple Computer, Inc.
Using the Entry Cache Efficiently
Whenever you access a slot in a soup entry, the system reads the entire entry into
the NewtonScript heap if it is not already present. That is, simply testing or
printing the value of a single slot causes the entire soup entry in which it resides to
be read into the entry cache. For best performance, avoid creating cached entries
when you don't need them, and flush the entry cache as soon as is appropriate. This
section describes how you can avoid unnecessary caching and how you can reclaim
cache memory explicitly. Table 11-1 on page 11-63 summarizes the use of the
entry cache by the functions and methods described in this discussion.
Reading a soup entry into memory requires more heap space than testing tag or
index values does. Whenever possible, work with index keys and tags rather than
the contents of soup entries. Some suggested techniques for doing so include
functions in favor of using
functions in your queries, as the latter can be performed without reading soup
entries into memory.
Query on index key values or tag values rather than on values that require
reading soup entries into the NewtonScript heap.
Use the cursor method
to retrieve an entry's key value without
reading the entry into the NewtonScript heap.
Normally, adding or changing a soup entry creates a cached entry. If you do not
plan on working further with an entry's data after you've added or modified it, you
can reclaim heap space by releasing the memory used by the entry cache. You can
soup method to add a soup entry without creating a
cached entry at all; in addition to saving heap space, this method saves you the time
normally required to create the cached entry. When working with a cached entry,
you can use the
function to write it back to its soup and clear
the entry cache.