refactor(oakundo): replace the CHandle vtable layer with owned trait objects

With the C ABI facade (oakengine) retired, the frozen-ABI rationale is
gone. UndoCommand now boxes a Send Command trait (new/from_closures/
multi), dropping OakUndoCommandVtable, the userdata trampolines, the
refcount shell, the handle module, and all undostack_* handle exports.
The global facade loses its raw-pointer out-params (can_undo/can_redo
return bool, command_name returns String). oaktimeline/oaknode/
oakplugin/oaktask construct commands directly via UndoCommand::new.
oakundo src is now free of unsafe; behavior (ordering, idempotence,
done flags, groups, observers, 200-row cap) is unchanged and pinned by
the rewritten tests.
This commit is contained in:
2026-08-19 00:41:49 +08:00
parent e0aa597f1e
commit 194d761ade
28 changed files with 409 additions and 2482 deletions
+9 -8
View File
@@ -16,19 +16,20 @@
//! # oaktimeline — the timeline edit module (Rust)
//!
//! Reimplements the C++ oaktimeline module (`src/timeline/src`) behind
//! its frozen C ABI (`include/timeline/*.h`). See README.md for the
//! architectural mapping (per-header domain modules, no UndoCommand
//! inheritance → vtable commands).
//! Reimplements the C++ oaktimeline module (`src/timeline/src`). See
//! README.md for the architectural mapping (per-header domain modules, no
//! UndoCommand inheritance → boxed `oakundo` command values).
//!
//! ## Single-lib unification
//!
//! The C ABI export layer (`ffi.rs`) and the oaknode/oakundo/oakcommon
//! bridge (`bridge/`) were deleted in the single-lib unification: undo
//! commands are now `oakundo::undocommand::UndoCommand` values and every
//! node/block/track reference is a [`util::NodeRef`] — an
//! `Arc<Mutex<oaknode::project::Project>>` + `oaknode::id::NodeId` pair
//! that the commands manipulate through the oaknode Rust domain directly.
//! commands are now `oakundo::undocommand::UndoCommand` values (the
//! crate's command structs implement `undocommon::Command` and are boxed
//! as trait objects) and every node/block/track reference is a
//! [`util::NodeRef`] — an `Arc<Mutex<oaknode::project::Project>>` +
//! `oaknode::id::NodeId` pair that the commands manipulate through the
//! oaknode Rust domain directly.
#![deny(unsafe_op_in_unsafe_fn)]
#![warn(missing_docs)]
+6 -6
View File
@@ -244,7 +244,7 @@ fn rational_abs(r: Rational) -> Rational {
// ---------------------------------------------------------------------------
// Marker undo commands. Each struct exposes prepare()/redo()/undo(); the
// undo stack wraps it through undocommon's vtable (to_command()).
// undo stack wraps it through undocommon's box_command (to_command()).
// ---------------------------------------------------------------------------
/// `MarkerAddCommand` (timelinemarker.h).
@@ -333,7 +333,7 @@ impl MarkerAddCommand {
}
}
/// Wrap as an oakundo vtable command handle.
/// Wrap as an oakundo command handle.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -407,7 +407,7 @@ impl MarkerRemoveCommand {
}
}
/// Wrap as an oakundo vtable command handle.
/// Wrap as an oakundo command handle.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -500,7 +500,7 @@ impl MarkerChangeColorCommand {
}
}
/// Wrap as an oakundo vtable command handle.
/// Wrap as an oakundo command handle.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -589,7 +589,7 @@ impl MarkerChangeNameCommand {
}
}
/// Wrap as an oakundo vtable command handle.
/// Wrap as an oakundo command handle.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -685,7 +685,7 @@ impl MarkerChangeTimeCommand {
}
}
/// Wrap as an oakundo vtable command handle.
/// Wrap as an oakundo command handle.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
+3 -3
View File
@@ -399,7 +399,7 @@ impl MultiCamEnableCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
crate::undocommon::box_command(self)
}
@@ -550,7 +550,7 @@ impl MultiCamDisableCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
crate::undocommon::box_command(self)
}
@@ -685,7 +685,7 @@ impl MultiCamSwitchCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
crate::undocommon::box_command(self)
}
+14 -88
View File
@@ -23,28 +23,14 @@
//!
//! `CHandleCommandWrapper` in C++ subclasses `olive::UndoCommand` to wrap a
//! raw `OakUndoCommand`; the Rust equivalent is the crate's own commands
//! boxed through [`box_command`], so the wrapper is gone.
use std::ffi::c_void;
//! boxed as trait objects through [`box_command`] (they implement
//! [`Command`] = `oakundo::undocommand::Command`), so the wrapper is gone.
use oaknode::graph::NodeEntry;
use oakundo::undocommand::{OakUndoCommandVtable, UndoCommand};
use oakundo::undocommand::UndoCommand;
use crate::util::{block_add_to_graph, block_remove_from_graph, NodeRef};
/// An empty (all callbacks absent) command — the failure-path result of
/// the deleted oaknode remove-command factory (an empty command handle).
pub(crate) fn empty_command() -> UndoCommand {
UndoCommand::from_vtable(
OakUndoCommandVtable {
redo: None,
undo: None,
free_fn: None,
},
std::ptr::null_mut(),
)
}
/// `oaknode_command_create_remove_node` — a command that detaches a node
/// from the project graph on `redo` (the detached entry is owned by this
/// command) and re-inserts it, identity-preserving, on `undo`. The C++
@@ -114,83 +100,23 @@ pub fn create_and_run_block_remove_command(block: &NodeRef) -> UndoCommand {
create_and_run_remove_command(block)
}
/// `free_command_handle`: release and null a command; NULL no-op. With the
/// `UndoCommand` value type, "freeing" is overwriting the pointee with an
/// empty command (the old value drops, running its `free_fn`).
pub fn free_command_handle(command: *mut UndoCommand) {
if command.is_null() {
return;
}
// SAFETY: the caller passes a valid pointer; overwriting drops the old
// value and installs the no-op command.
unsafe { *command = empty_command() };
}
/// Trait implemented by every timeline undo command (re-export of the
/// oakundo command trait). The crate's commands are boxed into an
/// [`UndoCommand`] via [`box_command`]; the command's
/// `redo_now`/`undo_now` dispatch to these callbacks.
pub use oakundo::undocommand::Command;
/// Trait implemented by every timeline undo command. The crate's commands
/// are boxed into an oakundo vtable command via [`box_command`]; the
/// command's `redo_now`/`undo_now` dispatch to these callbacks.
pub trait Command {
/// Apply the change.
fn redo(&mut self);
/// Revert the change.
fn undo(&mut self);
}
/// Generic `redo` callback forwarding to [`Command::redo`].
///
/// # Safety
/// `userdata` must be the `Box<T>` produced by [`box_command`].
unsafe extern "C" fn redo_cb<T: Command>(userdata: *mut c_void) {
if userdata.is_null() {
return;
}
// SAFETY: box_command allocated a `Box<T>`; still alive because the
// command owns it.
(unsafe { &mut *(userdata as *mut T) }).redo();
}
/// Generic `undo` callback forwarding to [`Command::undo`].
///
/// # Safety
/// `userdata` must be the `Box<T>` produced by [`box_command`].
unsafe extern "C" fn undo_cb<T: Command>(userdata: *mut c_void) {
if userdata.is_null() {
return;
}
// SAFETY: as `redo_cb`.
(unsafe { &mut *(userdata as *mut T) }).undo();
}
/// Generic `free` callback dropping the boxed command.
///
/// # Safety
/// `userdata` must be the `Box<T>` produced by [`box_command`].
unsafe extern "C" fn free_cb<T: Command>(userdata: *mut c_void) {
if userdata.is_null() {
return;
}
// SAFETY: the command owns this box; dropping it frees the command.
unsafe { drop(Box::from_raw(userdata as *mut T)) };
}
/// Box a command into an oakundo vtable command value. The command owns
/// the boxed `T`; `redo_now`/`undo_now` dispatch to `T::redo`/`T::undo`,
/// and dropping the command drops `T`.
/// Box a command into an oakundo command value. The command owns the
/// boxed `T`; `redo_now`/`undo_now` dispatch to `T::redo`/`T::undo`, and
/// dropping the command drops `T`.
pub(crate) fn box_command<T: Command + 'static>(cmd: T) -> UndoCommand {
let userdata = Box::into_raw(Box::new(cmd)) as *mut c_void;
let vtable = OakUndoCommandVtable {
redo: Some(redo_cb::<T>),
undo: Some(undo_cb::<T>),
free_fn: Some(free_cb::<T>),
};
// `from_vtable` copies the vtable and takes ownership of `userdata`.
UndoCommand::from_vtable(vtable, userdata)
UndoCommand::new(cmd)
}
/// `MultiUndoCommand` — a command that runs several child commands in order
/// on `redo` and in reverse on `undo` (timelineundocommon.h
/// `MultiUndoCommand`). Children are boxed `Command`s; the whole group wraps
/// into a single oakundo vtable command via [`box_command`].
/// into a single oakundo command via [`box_command`].
pub struct MultiUndoCommand {
/// Child commands, run in order on `redo`.
commands: Vec<Box<dyn Command>>,
@@ -214,7 +140,7 @@ impl MultiUndoCommand {
self.commands.is_empty()
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
+10 -10
View File
@@ -81,7 +81,7 @@ impl BlockResizeCommand {
block_set_length_and_media_out(&self.block, self.old_length);
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -134,7 +134,7 @@ impl BlockResizeWithMediaInCommand {
block_set_length_and_media_in(&self.block, self.old_length);
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -186,7 +186,7 @@ impl BlockSetMediaInCommand {
clip_set_media_in(&self.block, self.old_media_in);
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -325,7 +325,7 @@ impl TimelineAddTrackCommand {
c.track()
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -517,7 +517,7 @@ impl TimelineRemoveTrackCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -608,7 +608,7 @@ impl TransitionRemoveCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -833,7 +833,7 @@ impl TrackReplaceBlockWithGapCommand {
.push(TransitionRemoveCommand::new(relevant, true));
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -885,7 +885,7 @@ impl BlockEnableDisableCommand {
block_set_enabled(&self.block, self.old_enabled);
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -1073,7 +1073,7 @@ impl TrackListInsertGaps {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -1195,7 +1195,7 @@ impl TimelineAddDefaultTransitionCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
+4 -4
View File
@@ -277,7 +277,7 @@ impl BlockTrimCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -517,7 +517,7 @@ impl TrackSlideCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -672,7 +672,7 @@ impl TrackPlaceBlockCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -740,7 +740,7 @@ impl TrackMoveBlockCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
+10 -10
View File
@@ -129,7 +129,7 @@ pub struct TrackRippleRemoveAreaCommand {
track: NodeRef,
/// Area to clear.
range: TimeRange,
/// Whether `prepare` has run (the vtable command path never calls
/// Whether `prepare` has run (the oakundo command path never calls
/// `prepare()` itself, so `redo` derives the operations on first use).
prepared: bool,
/// Out-point trim on the first block (`timelineundoripple.h` `trim_out_`).
@@ -215,7 +215,7 @@ impl TrackRippleRemoveAreaCommand {
///
/// Mirrors the C++ algorithm (`oaknode_track_get_nearest_block_before_or_at`
/// is a direct oaknode-domain query; `redo` invokes this on first use
/// because the vtable command path never calls `prepare` itself).
/// because the oakundo command path never calls `prepare` itself).
pub fn prepare(&mut self) {
// Idempotent: recompute from the current track state, discarding any
// previously derived operations.
@@ -324,7 +324,7 @@ impl TrackRippleRemoveAreaCommand {
/// `redo`: apply the ripple removal.
pub fn redo(&mut self) {
// The vtable command path never invokes `prepare()` (the oakundo
// The oakundo command path never invokes `prepare()` (the oakundo
// wrapper only dispatches redo/undo), so derive the operations
// on first use.
if !self.prepared {
@@ -408,7 +408,7 @@ impl TrackRippleRemoveAreaCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -489,7 +489,7 @@ impl TrackListRippleRemoveAreaCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -555,7 +555,7 @@ impl TimelineRippleRemoveAreaCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -763,7 +763,7 @@ impl TrackListRippleToolCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -854,7 +854,7 @@ impl TimelineRippleDeleteGapsAtRegionsCommand {
///
/// The gap-kind, nearest-block, sequence-track and locked-flag queries
/// all go through the oaknode domain via `crate::util`; `redo` invokes
/// this on first use because the oakundo vtable wrapper only dispatches
/// this on first use because the oakundo command wrapper only dispatches
/// `redo`/`undo`.
pub fn prepare(&mut self) {
self.commands_.clear();
@@ -1025,7 +1025,7 @@ impl TimelineRippleDeleteGapsAtRegionsCommand {
/// `redo`: apply the gap deletions.
///
/// The vtable command path never invokes `prepare()` (the oakundo vtable
/// The oakundo command path never invokes `prepare()` (the oakundo
/// wrapper only dispatches `redo`/`undo`), so the sub-commands are built
/// on first use; later redos re-apply the stored commands.
pub fn redo(&mut self) {
@@ -1044,7 +1044,7 @@ impl TimelineRippleDeleteGapsAtRegionsCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
+5 -5
View File
@@ -183,7 +183,7 @@ impl BlockSplitCommand {
/// original span, so the out point is preserved exactly).
pub fn redo(&mut self) {
// Create the second half if redo is invoked without a preceding
// prepare() (the vtable command path may call redo directly).
// prepare() (the oakundo command path may call redo directly).
self.prepare();
// Re-attach the copied subgraph if a previous undo detached it.
self.re_attach_subgraph();
@@ -250,7 +250,7 @@ impl BlockSplitCommand {
self.new_block.clone()
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
crate::undocommon::box_command(self)
}
@@ -343,7 +343,7 @@ impl BlockSplitPreservingLinksCommand {
/// `redo`: redo every child command in order.
///
/// The vtable command path never invokes `prepare()` (the oakundo
/// The oakundo command path never invokes `prepare()` (the oakundo
/// wrapper only dispatches `redo`/`undo`), so the children are built
/// on first redo; `prepare` itself redoes each child as it builds it,
/// so the first redo has nothing left to run. Later redos (after an
@@ -385,7 +385,7 @@ impl BlockSplitPreservingLinksCommand {
None
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
crate::undocommon::box_command(self)
}
@@ -466,7 +466,7 @@ impl TrackSplitAtTimeCommand {
}
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
crate::undocommon::box_command(self)
}
+4 -4
View File
@@ -62,7 +62,7 @@ impl TrackRippleRemoveBlockCommand {
track_insert_block_after(&self.track, &self.block, self.before.as_ref());
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -107,7 +107,7 @@ impl TrackPrependBlockCommand {
track_ripple_remove_block(&self.track, &self.block);
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -159,7 +159,7 @@ impl TrackInsertBlockAfterCommand {
track_ripple_remove_block(&self.track, &self.block);
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
@@ -210,7 +210,7 @@ impl TrackReplaceBlockCommand {
track_replace_block(&self.track, &self.replace, &self.old);
}
/// Wrap as an oakundo vtable command value.
/// Wrap as an oakundo command value.
pub fn to_command(self) -> UndoCommand {
box_command(self)
}
+2 -2
View File
@@ -150,7 +150,7 @@ impl WorkareaSetEnabledCommand {
}
}
/// Wrap as an oakundo vtable command handle.
/// Wrap as an oakundo command handle.
pub fn to_command(self) -> UndoCommand {
crate::undocommon::box_command(self)
}
@@ -256,7 +256,7 @@ impl WorkareaSetRangeCommand {
}
}
/// Wrap as an oakundo vtable command handle.
/// Wrap as an oakundo command handle.
pub fn to_command(self) -> UndoCommand {
crate::undocommon::box_command(self)
}