GenericPlatformProcess.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "Containers/Array.h"
#include "Containers/UnrealString.h"
#include "CoreTypes.h"
#include "GenericPlatform/GenericPlatformAffinity.h"
#include "HAL/PlatformCrt.h"
#include "HAL/PlatformMisc.h"
#include "Misc/EnumClassFlags.h"
#include "Templates/Function.h"
#include "Templates/Tuple.h"
#include "Templates/SharedPointer.h"
 
class FEvent;
 
#if PLATFORM_CPU_X86_FAMILY
#include <immintrin.h>
#endif
 
#if PLATFORM_APPLE
#include <mach/mach_time.h>
#endif
 
#if !defined(__clang__)
#   include <intrin.h>
#   if defined(_M_ARM)
#       include <armintr.h>
#   elif PLATFORM_WINDOWS && PLATFORM_CPU_ARM_FAMILY
#       include <arm64intr.h>
#   endif
#endif
 
// Assume ThreadRipper is the max number of cores we can have
#if PLATFORM_DESKTOP
#define MAX_NUM_PROCESSORS 128
#else
#define MAX_NUM_PROCESSORS 16
#endif
 
 
class Error;
struct FProcHandle;
template <typename FuncType> class TFunctionRef;
 
namespace EProcessResource
{
    enum Type
    {
        VirtualMemory
    };
}
 
 
namespace ELaunchVerb
{
    enum Type
    {
        Open,
 
        Edit,
    };
}
 
namespace ENamedThreads
{
    enum Type : int32;
}
 
namespace UE::Core
{
    class FURLRequestFilter;
}
 
template< typename T, T InvalidHandleValue >
struct TProcHandle
{
    typedef T HandleType;
public:
 
    UE_FORCEINLINE_HINT constexpr TProcHandle()
        : Handle( InvalidHandleValue )
    { }
 
    UE_FORCEINLINE_HINT explicit TProcHandle( T Other )
        : Handle( Other )
    { }
 
    UE_FORCEINLINE_HINT T Get() const
    {
        return Handle;
    }
 
    UE_FORCEINLINE_HINT void Reset()
    {
        Handle = InvalidHandleValue;
    }
 
    UE_FORCEINLINE_HINT bool IsValid() const
    {
        return Handle != InvalidHandleValue;
    }
 
protected:
    T Handle;
};
 
 
struct FProcHandle;
 
struct FPlatformProcessMemoryStats
{
    uint64 UsedPhysical;
 
    uint64 PeakUsedPhysical;
 
    uint64 UsedVirtual;
 
    uint64 PeakUsedVirtual;
};
 
// Only used on Unix-like (Linux, Unix, Android) platforms because you have to scrape /proc/stat
namespace UE::Profiling
{
    struct FCPUStatTime{
        uint64_t            TotalTime;
        uint64_t            UserTime;
        uint64_t            NiceTime;
        uint64_t            SystemTime;
        uint64_t            SoftIRQTime;
        uint64_t            IRQTime;
        uint64_t            IdleTime;
        uint64_t            IOWaitTime;
    };
    
    struct FCPUState
    {
        constexpr static int32      MaxSupportedCores = MAX_NUM_PROCESSORS; 
        int32                       CoreCount;
        int32                       ActivatedCoreCount;
        ANSICHAR                    Name[6];
        FCPUStatTime                CurrentUsage[MaxSupportedCores]; 
        FCPUStatTime                PreviousUsage[MaxSupportedCores];
        int32                       Status[MaxSupportedCores];
        double                      Utilization[MaxSupportedCores];
        double                      IdleTime[MaxSupportedCores];
        double                      AverageUtilization;
        double                      AverageIdleTime;
    };
}
 
namespace UE::HAL
{
    struct FReadHandle
    {
        void* Value = nullptr;
        
        operator void*() const
        {
            return Value;
        }
    };
    
    struct FWriteHandle
    {
        void* Value = nullptr;
        
        operator void*() const
        {
            return Value;
        }
    };
    
    struct FProcessStartInfo
    {
        const TCHAR* Uri;
        const TCHAR* Arguments = TEXT("");
        const TCHAR* WorkingDirectory = nullptr;
        int32 PriorityModifier = 0;
        bool bDetached = false;
        bool bHidden = false;
        bool bInheritHandles = false;
        FReadHandle StdIn;
        FWriteHandle StdOut;
        FWriteHandle StdErr = StdOut;
    };
    
    enum struct EProcessId: uint32 {};
}
 
 
class IProcessSentinel
{
public:
    static bool CORE_API DoesSentinelFileExist(const TCHAR* Name, FString* OptionalOutContents=nullptr);
    
    virtual bool CreateSentinelFile(const TCHAR* Name, const FString& Contents) = 0;
 
protected:  
    virtual FString CORE_API MakeFilename(const TCHAR* Name);
    
    virtual bool DoesSentinelFileExistImpl(const TCHAR* Name, FString* OptionalOutContents=nullptr) = 0;
};
 
struct FGenericPlatformProcess
{
    struct FSemaphore
    {
        const TCHAR* GetName() const
        {
            return Name;
        }
 
        virtual void Lock() = 0;
 
        virtual bool TryLock(uint64 NanosecondsToWait) = 0;
 
        virtual void Unlock() = 0;
 
        FSemaphore(const FString& InName);
 
        FSemaphore(const TCHAR* InName);
 
        virtual ~FSemaphore() { };
 
    protected:
 
        enum Limits
        {
            MaxSemaphoreName = 128
        };
 
        TCHAR           Name[MaxSemaphoreName];
    };
 
    static CORE_API void* GetDllHandle( const TCHAR* Filename );
 
    static CORE_API void FreeDllHandle( void* DllHandle );
 
    static CORE_API void* GetDllExport( void* DllHandle, const TCHAR* ProcName );
 
    UE_FORCEINLINE_HINT static void AddDllDirectory(const TCHAR* Directory)
    {
 
    }
 
    UE_FORCEINLINE_HINT static void PushDllDirectory(const TCHAR* Directory)
    {
    
    }
 
    UE_FORCEINLINE_HINT static void PopDllDirectory(const TCHAR* Directory)
    {
 
    }
 
    UE_FORCEINLINE_HINT static void GetDllDirectories(TArray<FString>& OutDllDirectories)
    {
 
    }
 
    static CORE_API uint32 GetCurrentProcessId();
 
    static CORE_API uint32 GetCurrentCoreNumber();
    
    static bool GetPerFrameProcessorUsage(uint32 ProcessId, float& ProcessUsageFraction, float& IdleUsageFraction) {return false;}
 
    static CORE_API void SetThreadAffinityMask( uint64 AffinityMask );
 
    static CORE_API void SetThreadPriority( EThreadPriority NewPriority );
 
    static void SetThreadName( const TCHAR* ThreadName ) { }
 
    static CORE_API uint32 GetStackSize();
 
    static void DumpThreadInfo( const TCHAR* MarkerName ) { }
 
    static void SetupGameThread() { }
 
    static void SetupRenderThread() { }
 
    static void SetupAudioThread() { }
 
    static void TeardownAudioThread() { }
    
    static CORE_API bool ShouldSaveToUserDir();
 
    static CORE_API const TCHAR* BaseDir();
 
    static CORE_API const TCHAR* UserDir();
 
    static CORE_API const TCHAR *UserSettingsDir();
 
    static CORE_API const TCHAR *UserTempDir();
 
    static CORE_API const TCHAR *UserHomeDir();
 
    struct ApplicationSettingsContext
    {
        enum class Context : int8_t
        {
            LocalUser,
            RoamingUser,
            ApplicationSpecific
        };
        Context Location;
        bool bIsEpic;
    };
 
    static CORE_API const TCHAR* ApplicationSettingsDir();
    
    static CORE_API FString GetApplicationSettingsDir(const ApplicationSettingsContext& Settings);
 
    static CORE_API const TCHAR* ComputerName();
 
    static CORE_API const TCHAR* UserName(bool bOnlyAlphaNumeric = true);
    static CORE_API const TCHAR* ShaderDir();
    static CORE_API void SetShaderDir(const TCHAR*Where);
    static CORE_API void SetCurrentWorkingDirectoryToBaseDir();
 
    static CORE_API FString GetCurrentWorkingDirectory();
 
    static bool SetProcessLimits(EProcessResource::Type Resource, uint64 Limit)
    {
        return true;    // return fake success by default, that way the game won't early quit on platforms that don't implement this
    }
 
    static CORE_API const FString ShaderWorkingDir();
 
    static CORE_API void CleanShaderWorkingDir();
 
    static CORE_API const TCHAR* ExecutablePath();
 
    static CORE_API const TCHAR* ExecutableName(bool bRemoveExtension = true);
 
    static CORE_API FString GenerateApplicationPath( const FString& AppName, EBuildConfiguration BuildConfiguration);
 
    static CORE_API const TCHAR* GetArchitectureSuffix();
 
    static CORE_API const TCHAR* GetModulePrefix();
 
    static CORE_API const TCHAR* GetModuleExtension();
 
    static CORE_API const TCHAR* GetBinariesSubdirectory();
 
    static CORE_API const FString GetModulesDirectory();
 
    static CORE_API bool ModuleExists(const FString& Filename);
    
    static CORE_API void LaunchURL( const TCHAR* URL, const TCHAR* Parms, FString* Error );
 
    static CORE_API bool LaunchURLFiltered(const TCHAR* URL, const TCHAR* Parms, FString* Error, const UE::Core::FURLRequestFilter& Filter);
 
    static CORE_API bool CanLaunchURL(const TCHAR* URL);
    
    static CORE_API FString GetGameBundleId();
    
    static CORE_API FProcHandle CreateProc( const TCHAR* URL, const TCHAR* Parms, bool bLaunchDetached, bool bLaunchHidden, bool bLaunchReallyHidden, uint32* OutProcessID, int32 PriorityModifier, const TCHAR* OptionalWorkingDirectory, void* PipeWriteChild, void* PipeReadChild = nullptr);
    
    static CORE_API FProcHandle CreateProc( const TCHAR* URL, const TCHAR* Parms, bool bLaunchDetached, bool bLaunchHidden, bool bLaunchReallyHidden, uint32* OutProcessID, int32 PriorityModifier, const TCHAR* OptionalWorkingDirectory, void* PipeWriteChild, void* PipeReadChild, void* PipeStdErrChild);
 
    static CORE_API TTuple<FProcHandle, UE::HAL::EProcessId> CreateProc(const UE::HAL::FProcessStartInfo& StartInfo);
    
    static CORE_API FProcHandle OpenProcess(uint32 ProcessID);
 
    static CORE_API bool IsProcRunning( FProcHandle & ProcessHandle );
    
    static CORE_API void WaitForProc( FProcHandle & ProcessHandle );
 
    static CORE_API void CloseProc( FProcHandle & ProcessHandle );
 
    static CORE_API void TerminateProc( FProcHandle & ProcessHandle, bool KillTree = false );
 
    static CORE_API void TerminateProcTreeWithPredicate(
            FProcHandle& ProcessHandle,
            TFunctionRef<bool(uint32 ProcessId, const TCHAR* ApplicationName)> Predicate);
 
    enum class EWaitAndForkResult : uint8
    {
        Error,
        Parent,
        Child
    };
 
    static CORE_API EWaitAndForkResult WaitAndFork();
 
    static CORE_API bool GetProcReturnCode( FProcHandle & ProcHandle, int32* ReturnCode );
 
    static CORE_API bool IsApplicationRunning( uint32 ProcessId );
 
    static CORE_API bool IsApplicationRunning( const TCHAR* ProcName );
 
    static CORE_API FString GetApplicationName( uint32 ProcessId );
 
    static CORE_API bool GetApplicationMemoryUsage(uint32 ProcessId, SIZE_T* OutMemoryUsage);
 
    static CORE_API bool ExecProcess(const TCHAR* URL, const TCHAR* Params, int32* OutReturnCode, FString* OutStdOut, FString* OutStdErr, const TCHAR* OptionalWorkingDirectory = NULL, bool bShouldEndWithParentProcess = false);
 
    static CORE_API bool ExecElevatedProcess(const TCHAR* URL, const TCHAR* Params, int32* OutReturnCode);
 
    static CORE_API bool LaunchFileInDefaultExternalApplication( const TCHAR* FileName, const TCHAR* Parms = NULL, ELaunchVerb::Type Verb = ELaunchVerb::Open, bool bPromptToOpenOnFailure = true );
 
    static CORE_API void ExploreFolder( const TCHAR* FilePath );
 
#if PLATFORM_HAS_BSD_TIME 
 
    static CORE_API void Sleep( float Seconds );
    static CORE_API void SleepNoStats( float Seconds );
    [[noreturn]] static CORE_API void SleepInfinite();
    static CORE_API void YieldThread();
 
#endif // PLATFORM_HAS_BSD_TIME
 
    static CORE_API void ConditionalSleep(TFunctionRef<bool()> Condition, float SleepTime = 0.0f);
 
    // Message to others in the future, don't try to delete this function as it isn't exactly deprecated, but it should only ever be called from TEventPool::GetEventFromPool()
    UE_DEPRECATED(5.0, "Please use GetSynchEventFromPool to create a new event, and ReturnSynchEventToPool to release the event.")
    static CORE_API class FEvent* CreateSynchEvent(bool bIsManualReset = false);
 
    static CORE_API class FEvent* GetSynchEventFromPool(bool bIsManualReset = false);
 
    static CORE_API void FlushPoolSyncEvents();
 
    static CORE_API void ReturnSynchEventToPool(FEvent* Event);
 
    static CORE_API class FRunnableThread* CreateRunnableThread();
 
    static CORE_API void ClosePipe( void* ReadPipe, void* WritePipe );
 
    static CORE_API bool CreatePipe(void*& ReadPipe, void*& WritePipe, bool bWritePipeLocal = false);
 
    static CORE_API FString ReadPipe( void* ReadPipe );
 
    static CORE_API bool ReadPipeToArray(void* ReadPipe, TArray<uint8> & Output);
 
    static CORE_API bool WritePipe(void* WritePipe, const FString& Message, FString* OutWritten = nullptr);
 
    static CORE_API bool WritePipe(void* WritePipe, const uint8* Data, const int32 DataLength, int32* OutDataLength = nullptr);
 
 
    static CORE_API bool SupportsMultithreading();
 
    static CORE_API FSemaphore* NewInterprocessSynchObject(const FString& Name, bool bCreate, uint32 MaxLocks = 1);
 
    static CORE_API FSemaphore* NewInterprocessSynchObject(const TCHAR* Name, bool bCreate, uint32 MaxLocks = 1);
 
    static CORE_API bool DeleteInterprocessSynchObject(FSemaphore * Object);
 
    static CORE_API bool Daemonize();
 
    static CORE_API bool IsFirstInstance();
 
    static CORE_API void CeaseBeingFirstInstance();
 
    static CORE_API void TearDown();
 
    static bool SkipWaitForStats() { return false; }
 
    static bool TryGetMemoryUsage(FProcHandle& ProcessHandle, FPlatformProcessMemoryStats& OutStats) { return false; }
 
    static CORE_API ENamedThreads::Type GetDesiredThreadForUObjectReferenceCollector();
 
    static CORE_API void ModifyThreadAssignmentForUObjectReferenceCollector( int32& NumThreads, int32& NumBackgroundThreads, ENamedThreads::Type& NormalThreadName, ENamedThreads::Type& BackgroundThreadName );
 
    static CORE_API TSharedPtr<IProcessSentinel> CreateProcessSentinelObject();
 
    static CORE_API TSharedPtr<IProcessSentinel> CreateProcessSentinel(const TCHAR* Name, const FString& Contents); 
 
    static inline void Yield()
    {
#if PLATFORM_USE_SSE2_FOR_THREAD_YIELD
        _mm_pause();
#elif PLATFORM_CPU_ARM_FAMILY
#   if defined(_MSC_VER)
        __isb(0);
#   else
        __asm__ __volatile__("isb");
#   endif
#else
        // the platform with other architectures must override this to not have this function be called
        unimplemented();
#endif
    }
 
    static inline void YieldCycles(uint64 Cycles)
    {
#if PLATFORM_CPU_X86_FAMILY
        auto ReadCycleCounter = []()
        {
#if defined(_MSC_VER)
            return __rdtsc();
#elif PLATFORM_APPLE
            return mach_absolute_time();
#elif __has_builtin(__builtin_readcyclecounter)
            return __builtin_readcyclecounter();
#else
            // the platform with other architectures must override this to not have this function be called
            unimplemented();
#endif
        };
 
        uint64 start = ReadCycleCounter();
        //some 32bit implementations return 0 for __builtin_readcyclecounter just to be on the safe side we protect against this.
        Cycles = start != 0 ? Cycles : 0;
 
#if PLATFORM_WINDOWS
        if (FPlatformMisc::HasTimedPauseCPUFeature())
        {
            uint64 PauseCycles = ReadCycleCounter() + Cycles;
#if defined(_MSC_VER)
            _tpause(0, PauseCycles);
#elif __has_builtin(__builtin_ia32_tpause)
            __builtin_ia32_tpause(0, (uint32)(PauseCycles >> 32), (uint32)PauseCycles);
#else
#           error Unsupported architecture!
#endif
        }
        else
#endif
        {
            do
            {
                Yield();
            } while ((ReadCycleCounter() - start) < Cycles);
        }
 
#else
        // We can't read cycle counter from user mode on these platform
        for (uint64 i = 0; i < Cycles; i++)
        {
#if PLATFORM_CPU_ARM_FAMILY
#   if defined(_MSC_VER)
            __yield();
#   else
            __builtin_arm_yield();
#   endif
#else
#           error "Not implemented on this platform"
#endif
        }
#endif
    }
};