Details

Reviewers

Brecht Van Lommel (brecht)
Campbell Barton (campbellbarton)
Bastien Montagne (mont29)

Summary

Depends on: https://developer.blender.org/D3978

The depsgraph_update_pre/post handlers are useful when one is monitoring specific properties in Blender.
To fully replace the behavior of the scene_update_post/pre handlers we need more though.

This patch proposes a new bpy_extras.callback_utils module with two new functions (whose name can still change).

set_interval(function, interval): This registers a callback that should be called every interval seconds. When the function returns True, it will run again in the next interval. Otherwise it will be unregistered automatically.
run_in_main_thread: Sometimes it is useful to run a separate thread in Blender (e.g. for a simple server or for Python debugging). Currently there is no reliable way to change any Blender data from a separate thread. Using this utility function, addon developers can register a callback that will be executed one time, when Blender is in the right state.

Internally this behavior is implemented using a new _always handler that should maybe not be part of the official API. The behavior of it can still be archieved by registering a function with zero interval. For simplicity I think it is a good idea to implement this functionality in Python. The always_handler function tries to be as fast as possible in the common case.

Diff Detail

Repository

rB Blender

Branch

callback_utils (branched from blender2.8)

Build Status

Buildable 2525
Build 2525: arc lint + arc unit

Event Timeline

Jacques Lucke (JacquesLucke) created this revision.Thu, Nov 22, 5:53 PM

I think we should at least have a depsgraph_update_pre / depsgraph_update_post before we add this, so always doesn't get abused for the purpose of detecting changes.

The code for that could be in the same place as scene_update_pre / scene_update_post was, just only running the callback if DEG_id_type_any_updated() returns true.

ok, will add those two handlers in a separate diff.

Jacques Lucke (JacquesLucke) mentioned this in D3978: Python API: bpy.app.handlers.depsgraph_update_pre/post.Thu, Nov 22, 6:27 PM

rebase

On top of the always handler we can also implement another callback type. It could be used like this:

bpy_extras.handler_utils.run_in_main_thread(function)

internally it does this:

callbacks = queue.Queue()

def run_in_main_thread(function):
    callbacks.put_nowait(function)

def execute_queued_functions(_):
    while not callbacks.empty():
        function = execution_queue.get_nowait()
        function()

bpy.app.handlers.always.append(execute_queued_functions)

This could be used to encourage a best practice for this use case.
The execute_queued_functions callback can also only be added when the first callback is queued to eliminate any overhead when no addon uses it.

set_interval and run_in_main_thread

We could make it so that the always handler is not part of the "official" api.
Instead people should use these two new utility functions.

Harbormaster completed remote builds in B2519: Diff 12621.Fri, Nov 23, 11:26 AM

missing newline

Jacques Lucke (JacquesLucke) retitled this revision from Python API: bpy.app.handlers.always to Python API: callback_utils.Fri, Nov 23, 11:38 AM

Jacques Lucke (JacquesLucke) edited the summary of this revision. (Show Details)

I think this is a good solution to help addons do the right thing.

In D3977#90131, @Jacques Lucke (JacquesLucke) wrote:

We could make it so that the always handler is not part of the "official" api.
Instead people should use these two new utility functions.

Agreed. Is it automatically hidden in the API docs by naming it _always with the underscore? The description could mention that this is for internal use, and that callback_utils should be used instead.

rebase

It looks good to me, but wait for review from @Campbell Barton (campbellbarton).

release/scripts/modules/bpy_extras/callback_utils.py
46	Blenders -> Blender's

This revision is now accepted and ready to land.Fri, Nov 23, 12:30 PM

update bpy.app.handlers api docs
improve api docs

typo

Brecht Van Lommel (brecht) added inline comments.Fri, Nov 23, 3:23 PM

doc/python_api/examples/bpy.app.handlers.2.py
6–8	This example could show using `depsgraph.updates` to iterate over the list of changed datablocks, and `depsgraph.id_type_updated()` to figure out if there were any changes for a specific datablock type (mainly to detect potential removal of datablocks).

another example for monitoring properties

Brecht Van Lommel (brecht) mentioned this in D3990: Python API: bpy.app.timers (Python only).Mon, Nov 26, 12:36 AM

Would rather not have always handler, it encourages bad practice and will be used by addons even if we define it as internal-use-only.

If someone really wants they can define a timer, see: D3990 that executed immediately, at least in this case the API encourages the developer to consider a time when executing the next event is needed (instead of all the time).

This revision now requires changes to proceed.Mon, Nov 26, 1:34 AM

D3990 D3994

		Path
M		doc/python_api/examples/bpy.app.handlers.1.py (30 lines)
A	M	doc/python_api/examples/bpy.app.handlers.2.py (16 lines)
A	M	doc/python_api/examples/bpy.app.handlers.3.py (12 lines)
D	M	doc/python_api/examples/bpy.app.handlers.py (15 lines)
M		release/scripts/modules/bpy_extras/__init__.py (1 line)
A	M	release/scripts/modules/bpy_extras/callback_utils.py (90 lines)
M		source/blender/blenlib/BLI_callbacks.h (1 line)
M		source/blender/python/intern/bpy_app_handlers.c (3 lines)
M		source/blender/windowmanager/intern/wm_event_system.c (3 lines)

Diff	ID	Base	Description	Created	Lint	Unit
Base			Base
Diff 1	12609	e16ef56		Thu, Nov 22, 5:53 PM	★	★
Diff 2	12615	e16ef56	- rebase	Thu, Nov 22, 6:36 PM	★	★
Diff 3	12621	e16ef56	- set_interval and run_in_main_thread	Fri, Nov 23, 11:25 AM	★	★
Diff 4	12622	e16ef56	- missing newline	Fri, Nov 23, 11:27 AM	★	★
Diff 5	12624	4b06d0b	- rebase	Fri, Nov 23, 12:12 PM	★	★
Diff 6	12626	4b06d0b	- update bpy.app.handlers api docs	Fri, Nov 23, 1:21 PM	★	★
Diff 7	12627	4b06d0b	- typo	Fri, Nov 23, 1:22 PM	★	★
Diff 8	12630	4b06d0b	- another example for monitoring properties	Fri, Nov 23, 5:00 PM	★	★

Commit	Tree	Parents	Author	Summary	Date
118a518533f0	1d41f7195f36	241a006e452c	Jacques Lucke	another example for monitoring properties	Fri, Nov 23, 5:00 PM
241a006e452c	e352ffe42ad4	b50e85ee6042	Jacques Lucke	typo	Fri, Nov 23, 1:22 PM
b50e85ee6042	1a88ede650ac	291639830ffc	Jacques Lucke	improve api docs	Fri, Nov 23, 1:21 PM
291639830ffc	cfb3d136138d	36e565f53363	Jacques Lucke	update bpy.app.handlers api docs	Fri, Nov 23, 12:52 PM
36e565f53363	50dee450ed81	4b06d0bf51c3	Jacques Lucke	Python API: callback_utils	Fri, Nov 23, 12:12 PM

Python API: callback_utils
AbandonedPublic
Actions

Details

Diff Detail

Event Timeline

Revision Contents
Changeset List

Diff 12630

doc/python_api/examples/bpy.app.handlers.1.py

doc/python_api/examples/bpy.app.handlers.2.py

doc/python_api/examples/bpy.app.handlers.3.py

doc/python_api/examples/bpy.app.handlers.py

release/scripts/modules/bpy_extras/init.py

release/scripts/modules/bpy_extras/callback_utils.py

source/blender/blenlib/BLI_callbacks.h

source/blender/python/intern/bpy_app_handlers.c

source/blender/windowmanager/intern/wm_event_system.c

Python API: callback_utilsAbandonedPublicActions

Details

Diff Detail

Event Timeline

Revision ContentsChangeset List

Diff 12630

doc/python_api/examples/bpy.app.handlers.1.py

doc/python_api/examples/bpy.app.handlers.2.py

doc/python_api/examples/bpy.app.handlers.3.py

doc/python_api/examples/bpy.app.handlers.py

release/scripts/modules/bpy_extras/__init__.py

release/scripts/modules/bpy_extras/callback_utils.py

source/blender/blenlib/BLI_callbacks.h

source/blender/python/intern/bpy_app_handlers.c

source/blender/windowmanager/intern/wm_event_system.c

Python API: callback_utils
AbandonedPublic
Actions

Revision Contents
Changeset List

release/scripts/modules/bpy_extras/init.py