AllowSubmitIfVirtualizationFailed
AllowSubmitIfVirtualizationFailed
#Overview
name: AllowSubmitIfVirtualizationFailed
The value of this variable can be defined or overridden in .ini config files. 1
.ini config file referencing this setting variable.
It is referenced in 8
C++ source files.
#Summary
#Usage in the C++ source code
The purpose of AllowSubmitIfVirtualizationFailed is to control whether a source control submit operation should be allowed to proceed when the virtualization process fails. This setting is part of Unreal Engine’s virtualization system, which is used for managing large assets and data in game development.
The Unreal Engine subsystem that relies on this setting variable is the Virtualization system, specifically within the UE::Virtualization namespace. It’s primarily used in the FVirtualizationManager class, which is the main implementation of the IVirtualizationSystem interface.
The value of this variable is set through configuration files. It’s read in the FVirtualizationManager::ApplySettingsFromConfigFiles function, where it’s retrieved from the ConfigFile using the key “AllowSubmitIfVirtualizationFailed”.
This variable interacts with the source control system and the virtualization process. It’s used in conjunction with error handling and logging mechanisms when virtualization fails.
Developers must be aware that:
- This setting can significantly impact the workflow, as it determines whether failed virtualizations block submits or allow them to proceed with warnings.
- The default value is false, meaning submits are blocked if virtualization fails.
- It’s used in both editor (SSourceControlSubmit) and commandlet (UResavePackagesCommandlet) contexts.
Best practices when using this variable include:
- Carefully consider the implications of setting it to true, as it might lead to incomplete or inconsistent virtualization states.
- If set to true, ensure robust error logging and monitoring are in place to track failed virtualizations.
- Use in conjunction with other virtualization settings to create a comprehensive asset management strategy.
- Regularly review logs and errors when this setting is enabled to true, to catch and address virtualization issues promptly.
#Setting Variables
#References In INI files
Location: <Workspace>/Engine/Config/BaseEngine.ini:1471, section: [Core.VirtualizationModule]
- INI Section:
Core.VirtualizationModule
- Raw value:
false
- Is Array:
False
#References in C++ code
#Callsites
This variable is referenced in the following C++ source code:
#Loc: <Workspace>/Engine/Source/Developer/Virtualization/Private/VirtualizationManager.cpp:668
Scope (from outer to inner):
file
namespace UE::Virtualization
function bool FVirtualizationManager::AllowSubmitIfVirtualizationFailed
Source code excerpt:
}
bool FVirtualizationManager::AllowSubmitIfVirtualizationFailed() const
{
return bAllowSubmitIfVirtualizationFailed;
}
bool FVirtualizationManager::PushData(TArrayView<FPushRequest> Requests, EStorageType StorageType)
{
#Loc: <Workspace>/Engine/Source/Developer/Virtualization/Private/VirtualizationManager.cpp:1168
Scope (from outer to inner):
file
namespace UE::Virtualization
function void FVirtualizationManager::ApplySettingsFromConfigFiles
Source code excerpt:
{
ConfigFile.GetBool(ConfigSection, TEXT("AllowSubmitIfVirtualizationFailed"), bAllowSubmitIfVirtualizationFailed);
UE_LOG(LogVirtualization, Display, TEXT("\tAllowSubmitIfVirtualizationFailed : %s"), bAllowSubmitIfVirtualizationFailed ? TEXT("true") : TEXT("false"));
}
#if UE_VIRTUALIZATION_CONNECTION_LAZY_INIT == 0
ConfigFile.GetBool(ConfigSection, TEXT("LazyInitConnections"), bLazyInitConnections);
#Loc: <Workspace>/Engine/Source/Developer/Virtualization/Private/VirtualizationManager.h:106
Scope: file
Source code excerpt:
* on them. Typically this means appending the tag to the description of a changelist of
* packages. This value can be set to an empty string. [Default="#virtualized"]
* AllowSubmitIfVirtualizationFailed [bool]: Revision control submits that trigger the virtualization system can either allow or block
* the submit if the virtualization process fails based on this value. True will allow a
* submit with an error to continue and false will block the submit. Note that by error we mean
* that the packages were not virtualized, not that bad data was produced. [Default=false]
* LazyInitConnections [bool]: When true, backends will not attempt to connect to their services until actually required.
* This can remove lengthy connection steps from the process init phase and then only connect
* if we actually need that service. Note that if this is true then the connection can come from
* any thread, so custom backend code will need to take that into account. [Default=false]
* DisableLazyInitIfInteractive [bool] When true 'LazyInitConnections' will be forced to false if slate is enabled. This exists because
* some backends can show slate dialogs when their initial connection fails to prompt for the
* correct login values. When 'LazyInitConnections' is true, this request can come on any thread and
* trying to marshal the slate request to the gamethread can often introduce thread locks. Setting
* both this and 'LazyInitConnections' to true will allow tools that do not use slate to initialize
* the VA connections on use, but force tools that can display the slate dialog to initialized
* during preinit on the game thread so that the dialog can be shown. Note that this only overrides
the setting of 'LazyInitConnections' via the config file, not cvar, cmdline or code [Default=false]
* UseLegacyErrorHandling [bool]: Controls how we deal with errors encountered when pulling payloads. When true a failed payload
* pull will return an error and allow the process to carry on (the original error handling logic)
* and when false a dialog will be displayed to the user warning them about the failed pull and
* prompting them to retry the pull or to quit the process. [Default=true]
* PullErrorAdditionalMsg [string] An additional message that will be added to the error dialog presented on payload pull failure.
* This allows you to add custom information, such as links to internal help docs without editing
* code. Note that this additional message only works with the error dialog and will do nothing
* if 'UseLegacyErrorHandling' is true. [Default=""]
* ForceCachingOnPull [bool]: When true backends will be told to always upload the payload when a caching as a result of
* a payload pull as in this scenario we already know that the backend failed to pull the payload
* before it was pulled from a backend later in the hierarchy. Can be used to try and skip
* expensive existence checks, or if a backend is in a bad state where it believes it has the payload
* but is unable to actually return the data. [Default=false]
* UnattendedRetryCount [int32]: How many times the process should retry pulling payloads after a failure is encountered if the
process is unattended. Usually when a payload pull fails we ask the user to try and fix the issue
and retry, but in unattended mode we just log an error and terminate the process. In some cases
such as build machines with unreliable internet it is possible that the process could recover in
which case setting this value might help. Zero or negative values will disable the system.
Note: If many pulls are occurring at the same time on many threads a very short network outage might
spawn many errors in which case we try to group these errors into a single 'try' so 32 errors on 32
threads would not immediately blow past a retry count of 30 for example. [Default=0]
* UnattendedRetryTimer [int32] If 'UnattendedRetryCount' is set to a positive value then this value sets how long (in seconds)
* the process should wait after a failure is encountered before retrying the pull. Depending on the
likely cause of the failure you may want to set this value to several minutes. [Default=0]
*/
namespace UE::Virtualization
{
class FPullRequestCollection;
/** The default mode of filtering to use with package paths that do not match entries in UVirtualizationFilterSettings */
enum class EPackageFilterMode : uint8
{
/** Packages will be virtualized by default and must be opted out by the use of UVirtualizationFilterSettings::ExcludePackagePaths */
OptOut = 0,
/** Packages will not be virtualized by default and must be opted in by the user of UVirtualizationFilterSettings::IncludePackagePaths */
OptIn
};
/** Attempt to convert a string buffer to EPackageFilterMode */
bool LexTryParseString(EPackageFilterMode& OutValue, FStringView Buffer);
/** This is used as a wrapper around the various potential back end implementations.
The calling code shouldn't need to care about which back ends are actually in use. */
class FVirtualizationManager final : public IVirtualizationSystem
{
public:
using FRegistedFactories = TMap<FName, IVirtualizationBackendFactory*>;
using FBackendArray = TArray<IVirtualizationBackend*>;
FVirtualizationManager();
#Loc: <Workspace>/Engine/Source/Developer/Virtualization/Private/VirtualizationManager.h:185
Scope (from outer to inner):
file
namespace UE::Virtualization
class class FVirtualizationManager final : public IVirtualizationSystem
Source code excerpt:
virtual EPayloadFilterReason FilterPayload(const UObject* Owner) const override;
virtual bool AllowSubmitIfVirtualizationFailed() const override;
virtual bool PushData(TArrayView<FPushRequest> Requests, EStorageType StorageType) override;
virtual bool PullData(TArrayView<FPullRequest> Requests) override;
virtual EQueryResult QueryPayloadStatuses(TArrayView<const FIoHash> Ids, EStorageType StorageType, TArray<EPayloadStatus>& OutStatuses) override;
#Loc: <Workspace>/Engine/Source/Editor/SourceControlWindows/Private/SSourceControlSubmit.cpp:75
Scope (from outer to inner):
file
function bool TryToVirtualizeFilesToSubmit
Source code excerpt:
return true;
}
else if (System.AllowSubmitIfVirtualizationFailed())
{
for (const FText& Error : Result.Errors)
{
FMessageLog("SourceControl").Warning(Error);
}
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Commandlets/ContentCommandlets.cpp:1858
Scope (from outer to inner):
file
function bool UResavePackagesCommandlet::TryVirtualization
Source code excerpt:
return true;
}
else if (System.AllowSubmitIfVirtualizationFailed())
{
for (const FText& Error : Result.Errors)
{
UE_LOG(LogContentCommandlet, Warning, TEXT("%s"), *Error.ToString());
}
#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/Virtualization/VirtualizationSystem.cpp:78
Scope (from outer to inner):
file
namespace UE::Virtualization
class class FNullVirtualizationSystem : public IVirtualizationSystem
function virtual bool AllowSubmitIfVirtualizationFailed
Source code excerpt:
}
virtual bool AllowSubmitIfVirtualizationFailed() const override
{
return false;
}
virtual bool PushData(TArrayView<FPushRequest> Requests, EStorageType StorageType) override
{
#Loc: <Workspace>/Engine/Source/Runtime/Core/Public/Virtualization/VirtualizationSystem.h:600
Scope (from outer to inner):
file
namespace UE::Virtualization
class class IVirtualizationSystem
Source code excerpt:
* process failed. If it returns false then the calling code should prevent the submit.
*/
virtual bool AllowSubmitIfVirtualizationFailed() const = 0;
/**
* Push one or more payloads to a backend storage system. @See FPushRequest.
*
* @param Requests A collection of one or more payload push requests
* @param StorageType The type of storage to push the payload to, @See EStorageType for details.