Struct Transaction 

pub struct Transaction<'a, T: EngineCommandIssuer + ?Sized> { /* private fields */ }

An in-progress transaction. Create one by calling begin_transaction on any type that can receive commands.

You can send commands to a transaction, exactly like you can to an Engine. When you commit a transaction, all of the commands will be sent at once, atomically, with neither a gap nor any interleaving with any other commands. You can instead abort a transaction, in which case none of the commands will be sent.

It is perfectly legal to call begin_transaction on a transaction. You can go as deep as you like. If you do B = A.begin_transaction(), queue a bunch of commands, and then do B.commit(), all of those commands will be sent to A at once. If A is a transaction, then you still need to do A.commit() if you want the commands to be carried out, or you can do A.abort() to make it so that none of them happened at all.

Implementations

impl<'a, T: EngineCommandIssuer + ?Sized> Transaction<'a, T>

pub fn commit(self)

Commits an in-progress transaction. All commands will arrive at the Engine at the same time, in the correct order.

pub fn abort(self)

Aborts an in-progress transaction. None of the commands put into it will be issued.

Done implicitly if the transaction is not explicitly committed.

Trait Implementations

impl<'a, T: EngineCommandIssuer + ?Sized> EngineCommands for Transaction<'a, T>

fn begin_transaction(&mut self, length: Option<usize>) -> Transaction<'_, Self>

Starts a new transaction. Commands that are issued will be batched together into one transaction, and delivered and processed all at once when the transaction is complete.

fn replace_soundtrack(&mut self, new_soundtrack: Soundtrack)

Replace the active soundtrack with the given one. Currently-active nodes, sequences, and sounds will do their best to play to their conclusion.

fn precache(&mut self, flow_name: CompactString)

Requests that the given flow be precached for playback. The engine will attempt to load/preroll all requested sounds and streams in the background. Use is_flow_ready to determine when the loading is complete.

fn unprecache(&mut self, flow_name: CompactString)

Undoes a previous request that the given flow be precached for playback. This will lead the relevant sounds and streams to be purged once the flow stops playing (or immediately, if the flow is not currently playing).

fn unprecache_all(&mut self)

Undoes all previous requests for precaching of flows. Flows that are currently in use will still remain in memory.

fn is_flow_ready(&mut self, flow_name: CompactString) -> Response<bool>

Returns a query::Response that will answer the question “Is this flow I precached now ready for instant playback?”

fn is_flow_active(&mut self, flow_name: CompactString) -> Response<bool>

Returns a query::Response that will answer the question “Is this flow either currently playing or waiting to start playing?” (After a flow reaches a natural end without looping, this will return false.)

fn set_flow_control( &mut self, control_name: CompactString, new_value: StringOrNumber, )

Sets a given FlowControl to the given value.

fn get_flow_control( &mut self, control_name: CompactString, ) -> Response<Option<StringOrNumber>>

Returns a query::Response that will answer the question “What value does this flow control currently have?” (Flows can set flow control values themselves, and in doing so, communicate in a very limited way back to the calling program.)

fn get_all_flow_controls( &mut self, ) -> Response<Vec<(CompactString, StringOrNumber)>>

Returns a query::Response that will give you a complete list of flow controls, and the values they are currently set to.

fn get_active_flows(&mut self) -> Response<Vec<CompactString>>

Returns a query::Response that will give you a complete list of flows that are playing.

fn get_active_nodes(&mut self) -> Response<Vec<ActiveNodeReport>>

Returns a query::Response that will give you a complete list of flow nodes that are playing.

fn get_mix_control( &mut self, control_name: CompactString, ) -> Response<Option<f32>>

Returns a query::Response that will answer the question “What volume level is this mix control currently operating at?” If there is a fade in progress, the volume reported will reflect the current moment within the fade.

fn get_all_mix_controls(&mut self) -> Response<Vec<(CompactString, f32)>>

Returns a query::Response that will give you a complete list of mix controls, and the volumes they are currently operating at. If there is a fade in progress, the volumes reported will reflect the current moment within the fade.

fn get_mix_flows(&mut self) -> Response<Vec<MixFlowReport>>

Returns a query::Response that will give you a complete list of flows that are playing, and the volumes they’re playing at.

fn clear_flow_control(&mut self, control_name: CompactString)

Clears a given FlowControl, removing any previous value.

fn clear_prefixed_flow_controls(&mut self, control_prefix: CompactString)

Clears all FlowControls whose names strictly start with the given prefix.

fn clear_all_flow_controls(&mut self)

Clears all FlowControls.

fn fade_mix_control_to( &mut self, control_name: CompactString, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Fades a given MixControl to the given volume (0.0 to 1.0), using the given fading curve, over the given time period (in seconds).

fn fade_prefixed_mix_controls_to( &mut self, control_prefix: CompactString, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently existing mix controls whose names strictly start with the given prefix to the given volume (0.0 to 1.0), using the given fading curve, over the given time period (in seconds).

fn fade_all_mix_controls_to( &mut self, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently existing mix controls, including main, to the given volume (0.0 to 1.0), using the given fading curve, over the given time period (in seconds).

fn fade_all_mix_controls_except_main_to( &mut self, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently existing mix controls, except main, to the given volume (0.0 to 1.0), using the given fading curve, over the given time period (in seconds).

fn fade_mix_control_out( &mut self, control_name: CompactString, fade_length: PosFloat, fade_type: FadeType, )

Fades a given MixControl to zero volume, using the given fading curve, over the given time period (in seconds). When the fade is complete, the MixControl will be removed from existence rather than simply zeroed; future commands to “prefixed” and “all” will not resuscitate it (unless it is the target of a future, specific command).

fn fade_prefixed_mix_controls_out( &mut self, control_prefix: CompactString, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently existing mix controls whose names strictly start with the given prefix to zero volume, using the given fading curve, over the given time period (in seconds). When the fade is complete, the MixControl will be removed from existence rather than simply zeroed; future commands to “prefixed” and “all” will not resuscitate it (unless it is the target of a future, specific command).

fn fade_all_mix_controls_out( &mut self, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently existing mix controls, including main, to zero volume, using the given fading curve, over the given time period (in seconds). When the fade is complete, the MixControl will be removed from existence rather than simply zeroed; future commands to “prefixed” and “all” will not resuscitate it (unless it is the target of a future, specific command).

fn fade_all_mix_controls_except_main_out( &mut self, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently existing mix controls, except main, to zero volume, using the given fading curve, over the given time period (in seconds). When the fade is complete, the MixControl will be removed from existence rather than simply zeroed; future commands to “prefixed” and “all” will not resuscitate it (unless it is the target of a future, specific command).

fn kill_mix_control(&mut self, control_name: CompactString)

Kills a given MixControl instantly, as if you yanked an audio cable.

fn kill_prefixed_mix_controls(&mut self, control_prefix: CompactString)

Kills all MixControls whose names strictly start with the given prefix, as if you yanked an audio cable.

fn kill_all_mix_controls(&mut self)

Kills all MixControls, including main, as if you yanked an audio cable.

fn kill_all_mix_controls_except_main(&mut self)

Kills all MixControls, except main, as if you yanked an audio cable.

fn start_flow( &mut self, flow_name: CompactString, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Starts a given flow if it’s not already playing. If the flow is being newly started, it will be faded up from zero volume to the target volume, with the given fade curve. If the flow was already playing, acts just like fade_flow_to.

fn fade_flow_to( &mut self, flow_name: CompactString, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Fades a given flow to the given volume (0.0 to 1.0), using the given fading curve, over the given time period (in seconds). Does nothing if the flow is not currently playing.

fn fade_prefixed_flows_to( &mut self, flow_prefix: CompactString, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently playing flows whose names strictly start with the given prefix to the given volume (0.0 to 1.0), using the given fading curve, over the given time period (in seconds). Does nothing to flows that haven’t been started, or that have finished fading out.

fn fade_all_flows_to( &mut self, target_volume: PosFloat, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently playing flows to the given volume (0.0 to 1.0), using the given fading curve, over the given time period (in seconds). Does nothing to flows that haven’t been started, or that have finished fading out.

fn fade_flow_out( &mut self, flow_name: CompactString, fade_length: PosFloat, fade_type: FadeType, )

Fades a given flow to zero volume, using the given fading curve, over the given time period (in seconds). Does nothing if the flow is not currently playing, or has already faded out. When the fade is complete, the flow will be stopped.

fn fade_prefixed_flows_out( &mut self, flow_prefix: CompactString, fade_length: PosFloat, fade_type: FadeType, )

Fades all currently playing flows whose names strictly start with the given prefix to zero volume, using the given fading curve, over the given time period (in seconds). Does nothing to flows that haven’t been started, or that have already finished fading out.

fn fade_all_flows_out(&mut self, fade_length: PosFloat, fade_type: FadeType)

Fades all currently playing flows to zero volume, using the given fading curve, over the given time period (in seconds). Does nothing to flows that haven’t been started, or that have already finished fading out.

fn kill_flow(&mut self, flow_name: CompactString)

Kills a given flow instantly.

fn kill_prefixed_flows(&mut self, flow_prefix: CompactString)

Kills all currently playing flows whose names strictly start with the given prefix instantly.

fn kill_all_flows(&mut self)

Kills all currently playing flows instantly.