Q: What is the difference between the functions EntryFlushXMit and EntryChangeXMit?
A: The most important criterion when choosing between EntryFlushXMit and EntryChangeXMit is what will be done with the entry after the flush or change.
When an entry is added or changed, the system ensures that a cached entry frame exists in the NewtonScript heap. The system then writes the data in the frame to the store, skipping _proto slots. The result is that the data will be written to the store, and a cached frame will exist. Often, this is exactly what is desired because the entry is still needed since it will soon be accessed or modified.
In some cases, the data will be written to the soup with no immediate access afterwards. In other words, the data will not be used after being written to the soup. In these cases creating or keeping a cached entry frame in the NewtonScript heap is unnecessary and just wastes space and time. In these situations, EntryFlushXMit is a better option; it writes the data to the soup without creating the cached entry.
If any code accesses an entry that was just flushed, a new cached frame will be read in from the soup, just like when an existing entry is read for the first time.
The rule of thumb is: if an entry will be used soon after saving to the soup, then use AddXMit or EntryChangeXMit. If the entry will not soon be used again (so it doesn't need to take up heap space with the cached frame), then use AddFlushedXmit or EntryFlushXMit.
Some examples of good usage:
while entry do
begin
entry.fooCount := entry.fooCount + 1;
// nil appSymbol passed so don't broadcast
EntryFlushXMit(entry, nil);
entry := cursor:Next();
end; // Could broadcast now
foreach x in kInitialData do // if new, may not need broadcast
soup:AddFlushedXmit(Clone(x), nil);