au.DisableSubmixMutationLock

au.DisableSubmixMutationLock

#Overview

name: au.DisableSubmixMutationLock

This variable is created as a Console Variable (cvar).

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.DisableSubmixMutationLock is to control the locking mechanism for submix mutations in the audio mixer system of Unreal Engine 5. This setting variable is specifically related to the audio rendering system.

The Unreal Engine subsystem that relies on this setting variable is the Audio Mixer module, as evidenced by its usage in the AudioMixerDevice.cpp file.

The value of this variable is set through a console variable (CVar) system. It’s initialized to 0 by default, meaning the submix mutation lock is enabled. Developers can change this value at runtime using console commands.

The associated variable DisableSubmixMutationLockCVar directly interacts with au.DisableSubmixMutationLock. They share the same value, with DisableSubmixMutationLockCVar being used in the actual C++ code logic.

Developers must be aware that enabling this variable (setting it to 1) disables the submix mutation lock. This can have implications for thread safety in audio processing, potentially leading to race conditions if not used carefully.

Best practices when using this variable include:

  1. Only disable the lock if absolutely necessary and you understand the implications.
  2. If disabled, ensure that submix mutations are properly synchronized through other means.
  3. Use this setting primarily for debugging or performance optimization in specific scenarios.
  4. Always test thoroughly when changing this setting, especially in multi-threaded environments.

Regarding the associated variable DisableSubmixMutationLockCVar:

The purpose of DisableSubmixMutationLockCVar is to provide a C++ accessible flag that reflects the state of au.DisableSubmixMutationLock.

This variable is used within the Audio namespace, specifically in the FSubmixMap class methods. It controls whether certain operations on the SubmixMap use thread-safe locking mechanisms.

The value of this variable is set indirectly through the au.DisableSubmixMutationLock console variable.

DisableSubmixMutationLockCVar interacts directly with the SubmixMap operations, determining whether to use a mutex (MutationLock) for thread safety.

Developers must be aware that when this variable is set to a non-zero value, it bypasses the mutex-based thread safety measures in FSubmixMap operations.

Best practices for using DisableSubmixMutationLockCVar include:

  1. Treat it as a read-only variable in most cases, modifying it only through the console variable system.
  2. Be cautious when accessing or modifying the SubmixMap in multi-threaded contexts when this variable is set to a non-zero value.
  3. Use it in conjunction with other synchronization mechanisms if disabling the mutation lock.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerDevice.cpp:61

Scope: file

Source code excerpt:

static int32 DisableSubmixMutationLockCVar = 0;
FAutoConsoleVariableRef CVarDisableSubmixMutationLock(
	TEXT("au.DisableSubmixMutationLock"),
	DisableSubmixMutationLockCVar,
	TEXT("Disables the submix mutation lock.\n")
	TEXT("0: Not Disabled (Default), 1: Disabled"),
	ECVF_Default);

static int32 EnableAudibleDefaultEndpointSubmixesCVar = 0;

#Associated Variable and Callsites

This variable is associated with another variable named DisableSubmixMutationLockCVar. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerDevice.cpp:59

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 DisableSubmixMutationLockCVar = 0;
FAutoConsoleVariableRef CVarDisableSubmixMutationLock(
	TEXT("au.DisableSubmixMutationLock"),
	DisableSubmixMutationLockCVar,
	TEXT("Disables the submix mutation lock.\n")
	TEXT("0: Not Disabled (Default), 1: Disabled"),
	ECVF_Default);

static int32 EnableAudibleDefaultEndpointSubmixesCVar = 0;
FAutoConsoleVariableRef CVarEnableAudibleDefaultEndpointSubmixes(

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerDevice.cpp:121

Scope (from outer to inner):

file
namespace    Audio
function     void FSubmixMap::Add

Source code excerpt:

	void FSubmixMap::Add(const FSubmixMap::FObjectId InObjectId, FMixerSubmixPtr InMixerSubmix)
	{
		if (DisableSubmixMutationLockCVar)
		{
			SubmixMap.Add(InObjectId, InMixerSubmix);
		}
		else
		{
			FScopeLock ScopeLock(&MutationLock);

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerDevice.cpp:134

Scope (from outer to inner):

file
namespace    Audio
function     void FSubmixMap::Iterate

Source code excerpt:

	void FSubmixMap::Iterate(FIterFunc InFunction)
	{
		if (DisableSubmixMutationLockCVar)
		{
			for (const FPair& Pair : SubmixMap)
			{
				InFunction(Pair);
			}
		}

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerDevice.cpp:153

Scope (from outer to inner):

file
namespace    Audio
function     FMixerSubmixPtr FSubmixMap::FindRef

Source code excerpt:

	FMixerSubmixPtr FSubmixMap::FindRef(const FSubmixMap::FObjectId InObjectId) const
	{
		if (DisableSubmixMutationLockCVar)
		{
			return SubmixMap.FindRef(InObjectId);
		}
		else
		{
			FScopeLock ScopeLock(&MutationLock);

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerDevice.cpp:166

Scope (from outer to inner):

file
namespace    Audio
function     int32 FSubmixMap::Remove

Source code excerpt:

	int32 FSubmixMap::Remove(const FSubmixMap::FObjectId InObjectId)
	{
		if (DisableSubmixMutationLockCVar)
		{
			return SubmixMap.Remove(InObjectId);
		}
		else
		{
			FScopeLock ScopeLock(&MutationLock);

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerDevice.cpp:179

Scope (from outer to inner):

file
namespace    Audio
function     void FSubmixMap::Reset

Source code excerpt:

	void FSubmixMap::Reset()
	{
		if (DisableSubmixMutationLockCVar)
		{
			SubmixMap.Reset();
		}
		else
		{
			FScopeLock ScopeLock(&MutationLock);