Skip to content

start:

Introduction

The goals of the threading solution research are:
  • To establish how threading currently works in OpenOffice
  • To investigate issues related to running multiple scripts simultaneously in OpenOffice
  • To suggest how IDEs would be able to attach to OpenOffice scripts

Contents

Also of interest are these initial thoughts on the thread management topic posted to openoffice.org

Current StarBasic script threading behaviour

Run the macro from the "Macro" dialogbox.

  • No frozen document you can work on any documents
  • Macro running in background
  • No macro can be run
Assign the macro to the "F10" key. Press that key.
  • Active document is frozen
  • Other document are not frozen
  • Can't run any macro on other document while the macro is still running even from the "Macro" dialogbox.
While the macro is running, if you open the "Macro" dialogbox, the macro is paused
  • If you close the dialog box, the macro is resumed
  • If you decide to edit a macro, the macro is resumed and you can stop the macro from the BASIC editor
  • If you switch to the BASIC editor and click on the stop button, the macro will be stop but nothing in the UI will be updated until the "Macro" dialogbox is closed (this seems to be a bug).

Contents

Current Ms Basic script threading behaviour

Run the macro from the "Macro" dialogbox.

  • All document are frozen
Run the macro from the Ms Visual Basic editor.
  • All document are frozen
Assign the macro to the "F10" key. Press that key.
  • All document are frozen
Run a macro that will access Excel and change the cell values.
  • All word document are frozen
  • Excel is not frozen, macro is running and changing value and you can change values.

Contents

Event Handling

The OpenOffice process has multiple threads. Any thread that calls Application::Yield or Application::Reschedule dispatches GUI events. Dispatching GUI events requires the SolarMutex, so only one thread at a time can dispatch GUI events. In practice the "main" OpenOffice thread is the thread that dispatches most GUI events.

Events can be either synchronous or asynchronous.

Synchronous events are handled immediately, that means that the functionality bound to the event is invoked immediately from the call stack of the thread where the event occurred. The thread is therefore blocked until the event has been handled.

Asynchronous events are placed in a message queue by the thread handling the event, and the thread is not blocked, it continues executing. The message queue is serviced by any thread which calls Application::Yield or Application::Reschedule.

Contents

Options for script threading behaviour

There are two possible threading models that we could use:

  1. One script per OpenOffice process - this is the threading model currently used by OpenOffice.
  2. One script per OpenOffice document - this would allow more than one script to be run at the same time, but only one script could be run per document at a time. The thread running the script would have to grab a document lock before invoking the script and release it when the script has completed.

The best solution is to implement option 2, and add the possibility to configure the threading behaviour so that it acts like option 1 if the user wishes to use this behaviour (see Configuration section below).

So, how do we implement option 2? From discussions with Mathias Bauer and Joerg Budischweski they feel that OpenOffice should manage the spawning of the threads which would invoke the scripts. In the case of synchronous events the thread handling the event would spawn a thread in which it would then invoke the script. In the case of asynchronous threads the thread which had grabbed the event off the message queue would spawn a new thread when it wanted to invoke a script. In other words the responsibility for managing the per document script threads would lie with OpenOffice, not the scripting framework.

Changes needed:

  • The thread calling XFunction.invoke() (main thread for synchronous events, message queue thread for asynchronous events) needs to spawn a new thread and call XFunction.invoke() from there.
  • The document for which the XFunction is being invoked needs to be locked for the duration of XFunction.invoke() (with a documentmutex of some sort) so other XFunctions cannot be invoked for that document. The most difficult thing is that also every view that tries to modify a document must stick to this rule

See also: "Threading model for an office scripting framework" discussion on openoffice.udk.dev newsgroup

Contents

Issues with allowing one script per document

Because of problems with thread safety in the OpenOffice API it is currently unsafe to allow more than one thread to make API calls at the same time. For this reason there is a global SolarMutex which thread unsafe API implementations automatically lock before executing any functionality, and unlock before returning. The thread calling the OpenOffice API is not aware of this SolarMutex. While the SolarMutex is grabbed, OpenOffice API calls from other threads will block until the SolarMutex becomes free. The OpenOffice UI will be frozen while the SolarMutex is locked. If a script calls a OpenOffice API, the solarmutex will be grabbed until the API call returns which would temporarily freeze all document windows. These freezes may be an unacceptable annoyance to users and they may prefer that the UI be completely frozen for the duration of script execution rather than having it freeze unexpectedly.

See also: "Office API and thread safety" discussion on openoffice.framework.dev newsgroup

Contents

Configuration of threading behaviour

The threading behaviour of Office should be configurable so that the user can switch on/off the one script per document behaviour as they wish. A radio box should be added to the Scripting pane of the Office options dialog with the options:

Allow only one script to be run by OpenOffice at a time.
Allow one script per document to be run by OpenOffice at a time

Contents

Identifying script threads in a debugger

The issue here is how we can identify which thread in a OpenOffice process is running the script we are interested in debugging. This is possible in java using the java.lang.Thread.setName() method. The pairing of script name and document name should be sufficient to uniquely identify the appropriate thread.

Contents

SolarMutex

A problem could arise if a thread that does not possess the SolarMutex tries to execute a script synchronously, because any API call in the script can possibly acquire the SolarMutex. This may cause a deadlock, f.e. if the thread possessing the SolarMutex waits for a resource that is locked by the thread that tries to execute a script synchronously. So we could add some code here, that denies script execution, if it should be done synchronously and the SolarMutex is locked. It's better to treat this as an error than taking the risk of getting a deadlock.
======
suffice to say that for synchronous executions the thread owns the SolarMutex, it doesn't need to be the "main" thread.
======
Every not thread safe implementation of our API will acquire the SolarMutex in any interface call before anything will be done inside the method. So the function object doesn't need to care for that
======
the SolarMutex should be locked only inside the API calls (it will be anyway), not by the function object (it mustn't, because it doesn't know if it is called synchronously or not!), the event handler or anybody else. A big advantage of this is, that the SolarMutex will be freed between two API calls, giving the message queue a chance to allow for a minimum responsiveness of the office process. The script then will work in parallel to the event queue. Only for synchronous execution we should try to (!) acquire the SolarMutex before executing the script as described above. If the try fails, script execution should be denied. I consider this to be a rare case, currently I can't imagine that any event that may cause a script execution will occur in a thread without the SolarMutex. But it's good to handle this case in an appropriate way.
======

Contents