Signals

Manager::bulk_create(vec) and QuerySet::update_values(map) fire ONLY a bulk signal, never per-row post_save:

• Manager::bulk_create(vec) - fires bulk_post_save: once with { ids, created: true }.
  QuerySet::update_values(map) - fires bulk_post_save:
  once with { ids, created: false }.

  Manager::create(instance) fires post_save (per-row). Use it instead of bulk_create when you need a per-row signal.

  QuerySet::delete() and DynQuerySet::delete() (REST/admin) fire BOTH: bulk_post_delete:

  once with { ids }, AND a per-row post_delete: for every deleted row. The per-row payload is PK-only ({ "instance": { "": } }) unless something is actually subscribed to post_delete: - a subscriber present means the DELETE pays for RETURNING * and the payload carries the FULL row instead, same shape Manager::delete_instance uses. The full row still honors #[umbral(signal_skip)] on both paths - a skipped field never reaches the payload, whether the delete went through the typed or the dynamic (REST/admin) path. pre_delete is still Manager::delete_instance-only; there's no single moment to fire it for a multi-row DELETE.

  This is intentionally verbose - bulk deletes are usually hot paths where the cost of serialising every row to JSON and calling N signal handlers would be a surprise when nobody's listening. That's why the full-row cost is gated on post_delete:

  actually having a subscriber.

  Generic pub/sub - the escape hatch

  For application-defined events that aren't tied to a model lifecycle, the lower-level name-keyed API is still available:

  Code

  rust

  use umbral_signals::{subscribe_async, emit};
   
  subscribe_async("order_placed", |payload| async move {
      let order_id = payload["id"].as_i64().unwrap_or(0);
      // ...
  });
   
  // Anywhere:
  emit("order_placed", serde_json::json!({ "id": 42 })).await;
  

  Use any name except the ORM-reserved <event>:<table> format (pre_save:post, post_save:auth_user, etc.) to avoid collisions.

  A sync variant is also available for cheap, non-I/O handlers:

  Code

  rust

  use umbral_signals::subscribe;
   
  subscribe("page_view", |payload| {
      // Runs inline on the emitter's task. No await.
      tracing::debug!("page viewed: {:?}", payload["path"]);
  });
  

  Signal name format

  ORM signals use <event>:<table>:

  Signal	Table
  pre_save:post	post
  post_save:auth_user	auth_user
  pre_delete:comment	comment

  The on_model::<M>() API handles naming automatically. You only need the raw names if you're subscribing at the registry level with subscribe / subscribe_async.

  Payload shape

  For reference - the on_model API deserialises these for you, so you only need this when subscribing via the raw subscribe / subscribe_async functions:

  Signal	Payload
  pre_save, post_save	{ "instance": <M as JSON>, "created": bool }
  pre_delete, post_delete	{ "instance": <M as JSON> }

  Transactional writes (on_tx)

  A write made through Model::objects().on_tx(tx) (inside db::transaction(...), db::transaction_on(...), db::transaction_sqlite(...), or db::transaction_pg(...)) fires its post_save / post_delete / bulk_post_save / bulk_post_delete signals after the transaction commits, not while it's open. This matters because a naive "emit inline, mid-transaction" implementation is a phantom-signal bug: the signal (and any side effect a handler triggers) would fire even if the transaction later rolls back, telling subscribers about a write that never actually happened. Instead, each on_tx() write buffers its signal on the transaction, and the runner flushes that buffer only once commit() succeeds - a rollback simply drops the buffer, so a rolled-back write fires nothing.

  Code

  rust

  db::transaction(|tx| Box::pin(async move {
      Order::objects().on_tx(tx).create(new_order).await?;
      // post_save:order fires only after this closure returns Ok and the
      // transaction commits - never if it returns Err and rolls back.
      Ok::<_, MyError>(())
  })).await?;
  

  Boundary: this only applies to a transaction opened through one of the db::transaction* helpers, because those are the ones that own the commit call. A transaction you begin() and commit yourself (let mut tx = db::begin().await?; ...; tx.commit().await?;) is outside umbral's lifecycle - it has no hook to flush from, so any signals buffered on it are silently dropped when the Transaction value is dropped. Use db::transaction(...) (or its _on / _sqlite / _pg siblings) whenever you need signals to fire.

  What's not shipped at v0.0.1

  • Signal disconnect / per-call disable. Testing a handler today requires umbral_signals::clear_for_tests() to wipe all handlers and re-register. Targeted disconnect lands when tests need finer control.
  • Cross-process broadcast. A Redis or NATS adapter for horizontally-scaled deployments. Use umbral-tasks for cross-process work until then.
  • Typed events. An enum AppEvent { ... } shape with associated types so emitter and subscriber agree at compile time. Lands when a real plugin chain needs the guarantee.

  m2m_changed:<junction_table> is shipped. M2M::add/remove/set/clear each fire it automatically. See the ORM signals page for the payload shape and subscription example.

  See also

  • umbral-tasks plugin docs - the durable side of fire-and-forget work.
  • Settings and environment - reading config inside a signal handler.
  • Plugin trait - on_ready is the canonical place to register subscriptions.
  • arch.md - design rationale for the core-vs-plugin dependency inversion that makes the registry live in umbral-core.