FrameRateTask
Languages
Introduction
FrameRateTask
, a frame rate stabilizer, a tool to perform tasks at a stable frame rate.
This project aims to build an engine that can execute a task repeatedly and at high frequency in a single thread with a precise and stable time interval between every two executions as required. Also, this engine can provide real-time frame rate. This engine can be used to control game frame rate, network communication frame rate, etc.
Get This Package
To get this package, please enter the nuget package page: https://www.nuget.org/packages/FrameRateTask/
or use .NET CLI:
dotnet add package FrameRateTask
Author
Autor: Timothy-LiuXuefeng
Copyright (C) 2022 Timothy-LiuXuefeng
LICENSE
Contributing to this repository
Please read CONTRIBUTING carefully before contributing to this repository.
Interfaces
CSharp
class FrameRateTaskExecutor<TResult>
TResult
: The return value of the task.
-
Constructor:
-
FrameRateTaskExecutor(Func<bool> loopCondition, Func<bool> loopToDo, long timeInterval, Func<TResult> finallyReturn, long maxTotalDuration = long.MaxValue)
If the object is constructed with this constructor, when the
Start
orTryStart
method of the object is called, the procedure is equivalent to the following code:while (loopCondition && time <= maxTotalDuration) { if (!loopToDo()) break; /* Delay until the next frame arrives */ } return finallyReturn;
loopCondition
: The judgment condition of whether to continue the loop.loopToDo
: The loop body. If it returns false, jump out of the loop.timeInterval
: The time interval between two executions of the loop body in milliseconds.finallyReturn
: Specify the last code to be executed and the return value.maxTotalDuration
:The maximum time in milliseconds for the whole task,long.MaxValue
by default.
-
FrameRateTaskExecutor(Func<bool> loopCondition, Action loopToDo, long timeInterval, Func<TResult> finallyReturn, long maxTotalDuration = long.MaxValue)
The only difference with the previous constructor is that
loopToDo
has no return value so that you cannot jump out of the loop throughloopToDo
.
-
-
public void Start()
Start the task. If the task has already started, a
Timothy.FrameRateTask.TaskStartedMoreThanOnceException
exception will be thrown. Otherwise, it will start the task and return when the task finishes. -
public bool TryStart()
Try to start the task. Returns
false
if the task has already started, otherwise it will start the task and returntrue
when the task finishes. -
public uint FrameRate { get; }
The real-time frame rate of the loop body execution, initialized to the expected frame rate, and will be changed during the execution of the task.
-
public bool Finished { get; }
Whether the task has finished.
-
public bool HasExecuted { get; }
Whether the task has been started.
-
public TResult Result { get; }
The return value of the task. A
Timothy.FrameRateTask.TaskNotFinishedException
exception will be thrown if the task has not finished. -
public bool AllowTimeExceed { get; init; }
Whether to allow the execution timeouts,
true
by default. See the description ofMaxTolerantTimeExceedCount
for more details. -
public Action<bool> TimeExceedAction { init; }
It will be called after the execution timeouts. See the description of
MaxTolerantTimeExceedCount
for more details. -
public ulong MaxTolerantTimeExceedCount { get; init; }
The maximum number of consecutive timeouts allowed,
5
by default. Once a loop has timed out, if the number of consecutive timeouts does not exceedMaxTolerantTimeExceedCount
,TimeExceedAction
will be called with argumentfalse
. Otherwise, ifAllowTimeExceed
is set tofalse
, aTimothy.FrameRateTask.TimeExceedException
exception will be thrown; ifAllowTimeExceed
is set totrue
,TimeExceedAction
will be called with argumenttrue
, and the incomplete loop will be discarded and the loop count will be reset (see the exampleTemporaryCongestion
)