Asynchronous Interactions and Managing Modeless UI with Autodesk Revit API

Transcription

1 Asynchronous Interactions and Managing Modeless UI with Autodesk Revit API Arnošt Löbel Sr. Principal Software Engineer, Autodesk, Inc.

2 Class Summary In this class we will explore the realms of challenging workflows with the Revit API. You will learn common safe practices and you will understand the ways of the API. Together we will dive into the territory of asynchronous interactions with Revit and you will learn how to make such interactions efficient and safe.

3 Learning Objectives By the end of this class, you will: Understand the rules of safe interactions with the Revit API Learn the concept of controlling Revit asynchronously and the common pitfalls of such tasks Know how to use the Idling event to deliver results from an outside thread back to Revit Be able to streamline communications between an external modeless dialog and Revit Become familiar with using dynamic events to react to model changes

4 Knowledge is freedom The Revit API team wants to give API clients as much freedom as possible, but there are certain rules everyone should follow (and understand): 1. Thy shall not call the API unless invoked by it! 2. Thy shall not call the API from a different thread! 3. Thy shall call the API only, not the UI!

5 There s a jungle out there! (Randy Newman)

6 Things can go awry in asynchronous workflows Where s the danger? Why aren t we more protected? Secured gateways What could possibly happen? Scary stories to learn from The just reading case The case of crashed Revit The Russian Roulette case

7 Where is the danger? API clients make asynchronous calls mostly for good reasons, particularly to speed up Revit, but the outcome of unexpected invocations is often severe Documents will not be protected properly (no firewall!) Transaction and Regeneration mode not set Revit will not know the running application's ID The API scope is out of sync therefore events and updaters may behave unexpectedly

8 Why aren t we more protected? Most of unexpected calls either cause exceptions that would not happen otherwise, or miss on exceptions that should happen. Both cases could be equally dangerous. Revit cannot handle it because: Revit does not have a multi-thread-ready API Revit uses multi-threading internally only Revit uses a different thread context in the API API Firewall is not set around each every API call Revit doesn t expect API calls from other than the main Revit thread!

9 Secured gateways Execution tasks during which Revit expects API calls: A. The OnStartup and OnShutdown methods B. The Execute method of an external command C. Execution of a VSTA macro D. Handling an API event E. Invoking methods of a callback interface Outside of these tasks Revit does not know your application!

10 What could possibly happen? A. Nothing bad at all happens The call succeeds and all is fine (but would you bet on it?) B. Calls appear all right and returning successfully Though the gathered data are out of date or out of sync C. Calls fail, exceptions are thrown And this is actually a good scenario! D. Revit crashes, document(s) must be closed Frustration. Hard to determine whom to blame E. Revit model is corrupted by two independent processes In the worst case, the corrupted document is saved!

11 The just-reading case Consider for a moment one of the less severe scenarios when the asynchronous call (AC for short) just reads data from the model: 1. AC calls to get one parameter of a wall 2. Another application changes the wall on Idling 3. AC calls to get another parameter of the wall 4. An updater reacts to the change by another change 5. AC calls to get another parameter of the wall Though the calls were next to each other in the client s code, they were technically executed at different times and the data acquired by each of the methods reflects the state of the model at those different times.

12 The case of crashed Revit 1. User invokes an external command 2. Command splits a worker thread and waits for it to finish 3. The thread attempts to start a transaction 4. Revit throws an unhandled exception, possibly crashes How come this is an unsafe workflow? Because Revit API was called from another thread! What was the reason for the crash? Revit allocated memory in a wrong thread s context!

13 The Russian Roulette case Calling Revit API directly from a modeless dialog is not unlike betting in Las Vegas. One can gain something sometimes, but they will get you eventually. Applying it to our case something s going to crash. 1. Revit calls an external command 2. Command launches a modeless dialog and returns 3. The dialog awaits the user s requests 4. On a request, the dialog uses the API to modify the model The outcome of such calls is virtually unpredictable.

14 Happy Together (asynchronously)

15 Asynchronous workflows by the book Idling to the rescue The basic pattern A workflow with a twist Idling event s details Document-Changed event Code samples Modeless dialog Worker thread

16 Idling to the rescue 1. Use Idling to make API calls at unspecified times 2. Idling means Revit API is ready 3. DocumentChanged means Revit s done something 4. Those events are powerful when used together 5. Call to the API must be on the event s thread

17 The standard modeless pattern 1. An application registers itself and its commands 2. A command kicks off a modeless dialog and leaves it 3. The command registers for the Idling event 4. Command returns, Revit continues running 5. At times, Revit raises the Idling event 6. The event s handler checks if the dialog requested anything 7. If so, the handler takes the request and use the API 8. When the dialog is closed, it sets a flag somewhere 9. When flag is set, on next Idling the handler unregisters itself

18 Modeless dialog workflow Return to Revit Command or OnStart Dialog request Set (& wait) Create a Dialog Modeless Dialog Request_Id Make API Calls Unsubscribe from Idling Get & Reset No No Subscribe to Idling Request Handler Got a request? Dialog closed? Close Dialog Return to Revit Dialog Still open? No Idling raised OnShutDown

19 A workflow with a twist When changes to the model on individual interaction are not atomic, the Idling even is not enough; the DocumentChanged event must also be utilized. The differences from the basic workflow are: 1. Subscribe to Idling and DocumentChanged 2. On each document-changed event 1. Check if any data related to the process changed, and if so: 2. Clear the Model of the obsolete data 3. And restart the worker process

20 The Idling event s details Idling is a UI-concept It is in RevitAPIUI & the sender is UIApplication Idling is raised when: Revit is not doing anything and is ready to do something No command executing, no editor running, no transaction open Idling is raised a lot, it should not be abused Spend as little time in the handler as possible If you need to do more, do it in another thread Just being subscribed can slow down your computer Only subscribe when you need it And unsubscribe as soon as you do not need it

21 The DocumentChanged event Technically not part of a transaction Runs before a transaction ends but after Updaters It runs when a transaction is either committed or rolled back It also runs when transaction(s) is/are undone or redone Handler is not permitted to make model changes Handler has access to three sets of changed elements: Added elements Modified elements Deleted elements

22 How stuff works

23 How stuff works in the Revit API Regeneration modes Transaction modes Document modifiability Element validity Object lifespan API events External commands API callbacks Dynamic updaters API Scopes API Firewall

24 Regeneration modes Automatic mode is obsolete Only the Manual mode is supported It does not have to be declared (and should not be) Things to remember Programmers invoke regeneration as they need it A changed model should be regenerated before it is read from Regeneration is smart it only updates parts that need it End of a transaction always triggers regeneration A regeneration alone is sometimes not enough

25 Transaction modes Automatic mode For compatibility only (possibly going to be phased out) Manual mode The preferred way Read-Only mode Guarantees the active document does not get modified Transaction mode applies to external commands only Event handlers invoked during a command are on their own

26 Transactions Transactions may not be nested! Only groups and sub-transactions may be nested (properly) Transactions may fail - always check the status! Transaction being committed may actually return the RolledBack status instead of Committed API transaction failures are handled modally by default Modeless handling is possible, but requires using the Transaction Finalizer (use cautiously)

27 Document modifiability Document is Modifiable If it has an open transaction and is not in read-only state If a document is ReadOnly It is permanently or temporary in a read-only state Document is ReadOnlyFile This property only refers to the actual file on disk To be able to start a transaction: Document must not be read-only Document must not be modifiable yet

28 Element validity An element ceases to exist when: The element is deleted Creation of the element is undone Deletion of the element is redone The element-creating transaction was rolled back The native object is physically deleted The element comes back to life when: The deletion of the element was undone The creation of the element was redone (This resurrecting only works for elements)

29 Object lifespan Most objects are wrappers around native instances Some wrappers own native objects, some don t Control lifespan with the using block Particularly important with transaction phases Garbage collector takes care of managed objects But Revit does not delete collected native resources You can purge them explicitly by calling PurgeReleasedAPIObjects

30 API Event crash course Handlers are called on first-come-first-served basis Pre-events are raised before post-events Invocation loop stops by cancelling the event Post-events are always raised Document-level handlers are no longer called first Handlers are not permitted to use modeless failure handling Managed events depend on event observers in Revit There is an API Firewall around every call out A command that breaks the rules of the firewall will be discarded

31 API Events for the curious Managed events depend on native event observers in Revit All managed handlers of a particular event are grouped in one internal observer of that event Application vs. the Controlled Application events These subscriptions are virtually identical Subscribes are held in one common repository Unsubscribing from events during events is possible One can unsubscribe from any other event Even from the one currently being handled

32 External commands A command may be invoked only when: No other command is being executed No edit mode or editor is in effect No transaction or groups are open in the active document Revit does not guarantee any lifetime of a command Changes made by failed commands are discarded There is an API Firewall around every call out A command that breaks the rules of the firewall will be discarded

33 API callbacks Delegates given to Revit to be invoked later Callback classes names start with an I Dynamic updater - IUpdater Transaction Finalize - ITransactionFinalizer Callbacks are not just managed delegates Every callback has a native part, which is called first and bypasses the calls to the managed object Callbacks lifespan is not always controlled by Revit

34 Dynamic updaters They technically extend model regeneration outside of Revit They are invoked at the end of a committed transaction Updaters are not invoked for undone and redone transactions Registering and unregistering is not allowed during updates Certain API methods are forbidden during execution Updates provide access to changed elements: Added and deleted rule each other out Changed elements were neither added nor deleted

35 API Scope API Invocations may be nested, for example: Revit may invoke a command triggering an event to be handled triggering another event to be handled causing a dynamic updater to be executed The invoked executors may be from different applications Revit keeps a FILO stack of the executors Revit knows the application running atop And uses it sometimes to grant or refuse certain operations The first-level executor is responsible for mistakes

36 API Firewall It is around API invocations Particularly those allowed to have their own transactions It guards tasks to be finished properly Nothing is allowed to be left open in the active document If that happens, the procedure is rendered a failure If the active document is allowed to change: The formerly active document must be free of transactions This is currently allowed during commands only (not events)

37 Summary

38 What we have learned I shall not call the API unless invoked by it I shall not call the API from a different thread I shall call the API only, not the UI I shall use the Idling event efficiently

39 Questions?

40 Autodesk, AutoCAD* [*if/when mentioned in the pertinent material, followed by an alphabetical list of all other trademarks mentioned in the material] are registered trademarks or trademarks of Autodesk, Inc., and/or its subsidiaries and/or affiliates in the USA and/or other countries. All other brand names, product names, or trademarks belong to their respective holders. Autodesk reserves the right to alter product and services offerings, and specifications and pricing at any time without notice, and is not responsible for typographical or graphical errors that may appear in this document., Inc. All rights reserved.