Updating to v0.15 may require a (minor) update to some scripts

A note to clients running Toolkit on your render farm or using advanced customizations --  you may have to make some changes when you upgrade the Toolkit core to v0.15. As you may have heard the release of the v0.15 Core API brings a large update to the way Toolkit deals with the path cache. The update improves both the performance and reliability of the path cache database. Specifically (from the release notes):


Instead of keeping a shared path cache file to track the bindings between folders on disk and Shotgun entities, this information is pushed into Shotgun - via the FilesystemLocation entity. Each user will have their own version of the path cache and this is synchronized in the background whenever applications are launched or folders are created.


However, this new behavior may also require you to add a minor update to some of your scripts in order to sync the local path cache with the server. In particular, if you have any scripts on your render farm that use Toolkit, you'll want to add the following line before trying to create a context object from your path (tk is your SGTK instance):

# make sure we have synchronized the file system structure from
# Shotgun (for core v0.15 and above):


Note: If you don't have any custom scripts or apps, or your head is starting to spin in confusion, don't fret... this doesn't apply to you and you can go about your day.


What does this do?

tk.synchronize_filesystem_structure() synchronizes the master path cache in Shotgun with the local cache db on your machine. Check out the docs for more info.

Why do we have to do this?

context_from_path() uses the path cache database to lookup the Shotgun entity associated with the path. With this new path cache behavior, there could be updates made to the master path cache stored in Shotgun that haven't yet been synchronized locally to your render farm machine. So if the path doesn't exist, then you may get an empty context object which could cause errors in your script(s). Running tk.synchronize_filesystem_structure() ensures that the local cache is up to date.

Easy enough. But will this impact performance?

The first time you run tk.synchronize_filesystem_structure() it may take a few seconds to prime the local cache depending on the number of entries in your path cache. After the first sync though, subsequent calls to sync the path cache are incremental and will only sync the entries since the last update so it should be quick.

Why don't you do this automatically?

The synchronization is implicitly carried out as part of the normal folder creation process (which also happens when launching DCCs). However, there are cases where you're not creating folders but need an updated path cache, for example, on the render farm.

Are there any other places I will have to udpate my code?

Maybe. If you have any apps that get launched from Shotgun or scripts that require folders to be up-to-date, you may have to add this line in there.

I'm not sure if I need this. How will I know?

If you start seeing errors or issues in your code because of an empty or incomplete context object, this is a big clue. Remember, since Toolkit uses the path cache to associate a path with entities in Shotgun, if it's not in sync it may not find the entities you expect even though they exist in Shotgun and their folders have been created already.

Still have questions?

Feel free to contact us at toolkitsupport@shotgunsoftware.com



Please sign in to leave a comment.