User guide

196
Calling evict() has the effect of clearing the scattered query cache completely. This is data that was asked for in the
process of cooking locations but wasn't in the ancestral path of the location being cooked. It also empties the scene
data store of any locations, which aren't in the ancestral path of primaryPathToKeep.
The explicit management of these caches is currently built into the FnSceneGraphIterator API, and in the Arnold and
PRMan renderer plug-ins. As an example, WriteRI_Group() demonstrates this:
childSgIterator = sgIterator.getFirstChild(EVICT_ON_CHILD_TRAVERSAL);
By making the management explicit but, in the majority of cases, handled by supplied APIs, you are given the
flexibility to manage eviction at a fine-grained level. It is envisaged that per-site customizations can be made to allow
custom attribute conventions, which indicate ‘eviction points’ during the traversal of the scene.
Client-Based Caching
When using Clients to consume scene graph data you are able to take advantage of per-client caching. This is useful if
you require a pool of all previously received location events, as the default behavior is for the Runtime to push the
LocationEvent to your Client and then to forget about it. The consequence of this is that the Runtime only sends you
a LocationEvent once. The API provides the following functions to manage this:
void setEventCachingEnabled(bool enabled);
This enables event caching on the Client, which causes all location events delivered to, and subsequently extracted
through getLocationEvents(), to be cached so they can be retrieved by a call to getCachedLocation().
bool isEventCachingEnabled() const;
Returns true if event caching is enabled.
std::pair<LocationData, bool> getCachedLocation(
const std::string & locationPath) const;
If event caching is enabled, this returns the location data most recently returned by getLocationEvents(). If there
are pending events to be retrieved by getLocationEvents() they are not added to the Client cache until
getLocationEvents() has been invoked. The function returns a pair containing the LocationData corresponding to
the specified scene graph location, and returns true if the cache lookup was successful. It returns false if an error
occurred for any reason.
NOTE: These are your own ‘private’ caches, unaffected by the evict() function, discussed earlier.
Op Best Practices Cheat Sheet
Here are a list of best practices you should attempt to follow in order for your Ops to run smoothly:
• Remember, the Runtime may evaluate your Op at many locations. If you read a file from disk, you may prefer to
implement appropriate (thread-safe) caching to prevent multiple disk reads.
• FnAttribute has serialization tools, which may be useful if you require any more persistent storage of specific data.
24 OP API | OP BEST PRACTICES CHEAT SHEET