feat!: Rename `recursion_mode` to `reemission`. Rename `deferred` to `queued`. Add `latest-only` mode. (technically breaking)

[tlambert03]

This PR renames the parameter controlling how callbacks are (re-)invoked when one of the callbacks itself emits the signal currently being emitted. From the new docstrings:

reemission : Literal["immediate", "queued", "latest-only"] | None
    Determines the order and manner in which connected callbacks are invoked when a
    callback re-emits a signal. Default is `"immediate"`.

• "immediate": Signals emitted by callbacks are immediately processed in a deeper emission loop, before returning to process signals emitted at the current level (after all callbacks in the deeper level have been called).

• "queued": Signals emitted by callbacks are enqueued for emission after the current level of emission is complete. This ensures all connected callbacks are called with the first emitted value, before any of them are called with values emitted while calling callbacks.

• "latest-only": Signals emitted by callbacks are immediately processed in a deeper emission loop, and remaining callbacks in the current level are never called with the original value.

@Czaki, I was thinking this might actually be the desired behavior for evented models, since it not only makes sure that the current value is always up to date, it also prevents emitting things that are just about to become irrelevant

---

note: this is technically a breaking change, but we just barely introduced the recursion_mode feature a week or two ago... so there won't be a deprecation

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 100.00%. Comparing base (f6cebcb) to head (277f8c6).

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #296 +/- ## ========================================= Coverage 100.00% 100.00% ========================================= Files 22 22 Lines 2009 2033 +24 ========================================= + Hits 2009 2033 +24 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[codspeed-hq[bot]]

CodSpeed Performance Report

Merging #296 will degrade performances by 13.15%

_{Comparing tlambert03:immediate-drop (277f8c6) with main (f6cebcb)}

Summary

❌ 1 (👁 1) regressions ✅ 65 untouched benchmarks

Benchmarks breakdown

	Benchmark	main	tlambert03:immediate-drop	Change
👁	test_create_signal_instance	45.4 µs	52.3 µs	-13.15%

[tlambert03]

side question: Do you think you would probably use this mode over 'deferred' for cases like EventedModel when the primary goal of the emitter is to emit the current value?

[tlambert03]

oh and also: do you like the name immediate-drop? or can you think of a better one?

[Czaki]

side question: Do you think you would probably use this mode over 'deferred' for cases like EventedModel when the primary goal of the emitter is to emit the current value?

Yes. I think it will be better, as in most use cases I need to know only the last value.

oh and also: do you like the name immediate-drop? or can you think of a better one?

I do not have a better name, but I'm bad at naming. Maybe @jni could help.