Merge pull request #37 from Timothy-Liuxf/master

publish: version v1.1.2

Author: Timothy-Liuxf

CSharp/FrameRateTask/Exceptions.cs

@@ -13,7 +13,7 @@
 namespace Timothy.FrameRateTask
 {
 	/// <summary>
-	/// This exception will be throwed when the task hasn't finished but is asked to get the return value.
+	/// This exception will be thrown when the user gets the return value without the task finished.
 	/// </summary>
 	public class TaskNotFinishedException : Exception
 	{
@@ -22,7 +22,7 @@ public class TaskNotFinishedException : Exception
 	}
 
 	/// <summary>
-	/// This exception will be throwed when the time interval specified is invalid.
+	/// This exception will be thrown when the time interval specified is invalid.
 	/// </summary>
 	public class IllegalTimeIntervalException : Exception
 	{
@@ -31,7 +31,7 @@ public class IllegalTimeIntervalException : Exception
 	}
 
 	/// <summary>
-	/// This exception will be throwed when time exceeds but time exceeding is not allowed.
+	/// This exception will be thrown when time exceeds but time exceeding is not allowed.
 	/// </summary>
 	public class TimeExceedException : Exception
 	{
@@ -40,12 +40,12 @@ public class TimeExceedException : Exception
 	}
 
 	/// <summary>
-	/// This exception will be throwed when the task has been started but is asked to be started again.
+	/// This exception will be thrown when the user trys to start a task which has started.
 	/// </summary>
 	public class TaskStartedMoreThanOnceException : Exception
 	{
 		///
-		public override string Message => "The task has been started more than once!";
+		public override string Message => "The task has started more than once!";
 	}
 
 }

CSharp/FrameRateTask/FrameRateTask.cs

@@ -15,13 +15,13 @@ namespace Timothy.FrameRateTask
 {
 
 	/// <summary>
-	/// The class intends to execute a task that need to be executed repeatedly every less than one second and need to be accurate.
+	/// The class intends to execute a task which needs to be executed repeatedly every less than one second accurately.
 	/// </summary>
 	/// <typeparam name="TResult">The type of the return value of the task.</typeparam>
 	public class FrameRateTaskExecutor<TResult>
 	{
 		/// <summary>
-		/// The actual framerate recently.
+		/// The current actual frame rate.
 		/// </summary>
 		public uint FrameRate
 		{
@@ -62,7 +62,7 @@ private bool TrySetExecute()
 
 		private TResult result;
 		/// <summary>
-		/// Get the return value of this task.
+		/// Get the return value of the task.
 		/// </summary>
 		/// <exception cref="TaskNotFinishedException">
 		///		The task hasn't finished.
@@ -81,7 +81,7 @@ public TResult Result
 		/// Gets or sets whether it allows time exceeding.
 		/// </summary>
 		/// <remarks>
-		/// If this property is false, the task will throw a TimeExceed exception when the task cannot finish in the given time.
+		/// If it is set false, the task will throw Timothy.FrameRateTask.TimeExceedException when the task cannot finish in the given time.
 		/// The default value is true.
 		/// </remarks>
 		public bool AllowTimeExceed
@@ -95,10 +95,10 @@ public bool AllowTimeExceed
 		} = true;
 
 		/// <summary>
-		/// It will be called once time exceeds if AllowTimeExceed is set true.
+		/// It will be called once time exceeds.
 		/// </summary>
 		/// <remarks>
-		/// parameter bool: If it is called because of the number of time exceeding is greater than MaxTimeExceedCount, the argument is true; if it is called because of exceeding once, the argument is false.
+		/// parameter bool: If it is called because of the number of time exceeding is greater than MaxTolerantTimeExceedCount, the argument is true; if it is called because of exceeding once, the argument is false.
 		/// </remarks>
 		public Action<bool> TimeExceedAction
 		{
@@ -130,7 +130,7 @@ public ulong MaxTolerantTimeExceedCount
 		/// Start this task synchronously.
 		/// </summary>
 		/// <exception cref="TaskStartedMoreThanOnceException">
-		/// the task has been started.
+		/// the task has started.
 		/// </exception>
 		public void Start()
 		{
@@ -140,7 +140,7 @@ public void Start()
 		/// Try to start this task synchronously.
 		/// </summary>
 		/// <returns>
-		/// true if the task is started successfully; false if the task has been started.
+		/// true if the task starts successfully; false if the task has started.
 		/// </returns>
 		public bool TryStart()
 		{
@@ -154,11 +154,11 @@ public bool TryStart()
 		/// <summary>
 		/// Constructor
 		/// </summary>
-		/// <param name="loopCondition">If you want to continue to loop, return true; otherwise return false.</param>
+		/// <param name="loopCondition">If you want to continue to loop, return true; otherwise, return false.</param>
 		/// <param name="loopToDo">If you want to break out, return false; otherwise, return true.</param>
-		/// <param name="timeInterval"></param>
-		/// <param name="finallyReturn">The return value. It will be called after the loop.</param>
-		/// <param name="maxTotalDuration">The maximum time for the loop to execute.</param>
+		/// <param name="timeInterval">The time interval between two execution.</param>
+		/// <param name="finallyReturn">Used to set the return value. It will be called after the loop.</param>
+		/// <param name="maxTotalDuration">The maximum time for the loop to run.</param>
 		public FrameRateTaskExecutor
 			(
 				Func<bool> loopCondition,
@@ -235,11 +235,11 @@ public FrameRateTaskExecutor
 		/// <summary>
 		/// Constructor
 		/// </summary>
-		/// <param name="loopCondition">If you want to continue to loop, return true; otherwise return false.</param>
+		/// <param name="loopCondition">If you want to continue to loop, return true; otherwise, return false.</param>
 		/// <param name="loopToDo">Loop to do.</param>
-		/// <param name="timeInterval"></param>
-		/// <param name="finallyReturn">The return value. It will be called after the loop.</param>
-		/// <param name="maxTotalDuration">The maximum time for the loop to execute.</param>
+		/// <param name="timeInterval">The time interval between two execution.</param>
+		/// <param name="finallyReturn">Used to set the return value. It will be called after the loop.</param>
+		/// <param name="maxTotalDuration">The maximum time for the loop to run.</param>
 		public FrameRateTaskExecutor
 			(
 				Func<bool> loopCondition,

CSharp/FrameRateTask/FrameRateTask.csproj

@@ -2,18 +2,18 @@
 
   <PropertyGroup>
     <TargetFrameworks>netcoreapp3.1;net5.0;net6.0</TargetFrameworks>
-    <FileVersion>1.1.1.0</FileVersion>
-    <AssemblyVersion>1.1.1.0</AssemblyVersion>
-    <VersionPrefix>1.1.1</VersionPrefix>
-    <RepositoryUrl>https://github.com/Timothy-LiuXuefeng/FrameRateTask</RepositoryUrl>
+    <FileVersion>1.1.2.0</FileVersion>
+    <AssemblyVersion>1.1.2.0</AssemblyVersion>
+    <VersionPrefix>1.1.2</VersionPrefix>
+    <RepositoryUrl>https://github.com/Timothy-Liuxf/FrameRateTask</RepositoryUrl>
     <PackageReadmeFile>README.md</PackageReadmeFile>
-    <Authors>TimothyLiuXuefeng</Authors>
+    <Authors>Timothy Liu</Authors>
     <Company>$(Authors)</Company>
     <Copyright>Copyright (C) 2022</Copyright>
     <RepositoryType>git</RepositoryType>
     <PackageRequireLicenseAcceptance>True</PackageRequireLicenseAcceptance>
     <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
-    <PackageProjectUrl>https://github.com/Timothy-LiuXuefeng/FrameRateTask</PackageProjectUrl>
+    <PackageProjectUrl>https://timothy-liuxf.github.io/FrameRateTask</PackageProjectUrl>
     <Nullable>disable</Nullable>
     <Description>Frame rate stabilizer, a task executor which executes tasks at a stable frame rate.</Description>
   </PropertyGroup>

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright © 2022 Timothy-LiuXuefeng
+Copyright © 2022 Timothy Liu
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

README.md

@@ -2,54 +2,41 @@
 
 ---
 
-## Introduction
-
-Frame rate stabilizer, a task executor which executes tasks at a stable frame rate.  
+## Languages
 
-This project intends to build an engine to support to execute tasks which need to be execute repeatedly and frequently, and the time interval between two executing need to be accurately stable. And this engine can also provide the real-time frame rate. Up to now, this time interval should be no more than 1 second. It can be used to control the framerate of a game, and control the frame rate of communication through network, etc. 
+[English](https://github.com/Timothy-LiuXuefeng/FrameRateTask/blob/master/README.md)  
+[中文（简体）](https://github.com/Timothy-LiuXuefeng/FrameRateTask/blob/master/README.zh-CN.md)
 
-The source code of the dll is in the project FrameRateTask, and the example of usage is in the project Test.
+## Introduction
 
-This project is initially written for [THUAI4](https://github.com/eesast/THUAI4) to support some functions.
+`FrameRateTask`, a frame rate stabilizer, a task executor which executes tasks at a stable frame rate.  
 
->  帧率稳定器——以固定帧率执行任务。
->
->  本项目旨在构建一个可以重复、高频率执行一个任务的引擎，并且每两次执行的时间间隔有精确和稳定的需求。并且，本引擎还可以提供实时的帧率。目前本引擎仅支持的两次执行的时间间隔小于一秒钟。本引擎可以用来控制游戏帧数、网络通信帧率，等等。  
->
->  dll 的源代码在 FrameRateTask 项目中，使用示例代码在 Test 项目中。
->
->  本项目的编写最初是为了 [THUAI4](https://github.com/eesast/THUAI4) 来实现某些特定功能。  
+This project intends to build an engine to support executing tasks which need to be executed repeatedly and frequently in a single thread, and the time interval between two execution needs to be accurately stable. And this engine can also provide the real-time frame rate. Up to now, this time interval should be no more than 1 second. It can be used to control the frame rate of a game, or communication through network, etc. 
 
+The source code is in the project `FrameRateTask`, and the example of usage is in the project `Test`.
 
+> This project is initially written for [THUAI4](https://github.com/eesast/THUAI4) to support some functions.
 
 ## Get This Package
 
-To get this package, please enter nuget package page: [https://www.nuget.org/packages/FrameRateTask/](https://www.nuget.org/packages/FrameRateTask/)
+To get this package, please enter the nuget package page: [https://www.nuget.org/packages/FrameRateTask/](https://www.nuget.org/packages/FrameRateTask/)
 
 or use .NET CLI:  
 
 ```shell
 $ dotnet add package FrameRateTask
 ```
 
-
-
 ## Author
 
 Autor: Timothy-LiuXuefeng
 
-Job: Undergraduate in THU, major in EE
-
 Copyright (C) 2022 Timothy-LiuXuefeng
 
-
-
 ## LICENSE
 
 [MIT license](./LICENSE.txt)
 
-
-
 ## Interfaces  
 
 ### CSharp  
@@ -60,62 +47,64 @@ Copyright (C) 2022 Timothy-LiuXuefeng
 
 + Constructor:
 
-  + `FrameRateTaskExecutor(Func<bool> loopCondition, Func<bool> loopToDo, long timeInterval, Func<TResult> finallyReturn, long maxTotalDuration = long.MaxValue)`
-
-    > ```c#
-    > while (loopCondition && time <= maxTotalDuration)
-    > {
-    >     if (!loopToDo()) break;
-    >     /*Do something to delay.*/
-    > }
-    > return finallyReturn;
-    > ```
-    >
-    > + `loopCondition`: The condition to judge if the loop will continue. 是否继续循环的判断条件。
-    > + `loopToDo`: The loop body. If it returns false, jump out of the loop. 循环体。如果返回 `false`，跳出循环。
-    > + `timeInterval`: Time interval between two executing in milliseconds. 两次循环体执行的时间间隔，单位是毫秒。
-    > + `finallyReturn`: Specify the last thing to do and the return value. 指定最后要做的事情和返回值。
-    > + The maximum time in total for this task in milliseconds, `long.MaxValue` for default. 整个任务执行的最长时间，单位是毫秒。
+  + `FrameRateTaskExecutor(Func<bool> loopCondition, Func<bool> loopToDo, long timeInterval, Func<TResult> finallyReturn, long maxTotalDuration = long.MaxValue)`  
+
+    If the object is constructed by this constructor, when calling its the `Start` or `TryStart` method, the program behaves as below:  
+
+    ```c#
+    while (loopCondition && time <= maxTotalDuration)
+    {
+     if (!loopToDo()) break;
+     /* Do something to delay until next frame comes. */
+    }
+    return finallyReturn;
+    ```
+
+    + `loopCondition`: The condition to judge if the loop will continue.
+    + `loopToDo`: The loop body. If it returns false, jump out of the loop.
+    + `timeInterval`: Time interval between two executing in milliseconds.
+    + `finallyReturn`: Specify the last thing to do and the return value.
+    + `maxTotalDuration`：The maximum time in total for this task in milliseconds, `long.MaxValue` for default.
 
   + `FrameRateTaskExecutor(Func<bool> loopCondition, Action loopToDo, long timeInterval, Func<TResult> finallyReturn, long maxTotalDuration = long.MaxValue)`
 
-    > The only thing that is different from the last constructor is that `loopToDo` has no return value so you cannot jump out the loop through `loopToDo`.
-    >
-    > 与上一个构造函数唯一的不同是，`loopToDo` 没有返回值，因此你不能通过它跳出循环体。
+    The only thing different from the last constructor is that `loopToDo` has no return value so that you cannot jump out of the loop through `loopToDo`.
+
++ `public void Start()`
+
+  Start executing the task. If the task has started, it will throw `Timothy.FrameRateTask.TaskStartedMoreThanOnceException`. Otherwise, it will execute the task and return after the task finishes. 
+
++ `public bool TryStart()`
+
+  Try to start executing the task. If the task has started, it will return `false`. Otherwise, it will execute the task and return `true` after the task finishes.  
 
 + `public uint FrameRate { get; }`
 
-  > The real-time framerate, initialized with expected framerate, changed when the task is running. 任务执行的实时帧率，初始化为期待的帧率，会在任务执行时被改变。  
+  The real-time frame rate, initialized with the expected frame rate, and will be changed when the execution of the task.
 
 + `public bool Finished { get; }`
 
+  Whether the task has finished.
+
 + `public bool HasExecuted { get; }`
 
+  Whether the task has begun to execute.
+
 + `public TResult Result { get; }`
 
-  > The return value of the task. It will throw an exception if the task hasn't finished. 
-  >
-  > 任务的返回值。如果任务未执行完毕，将会抛出异常。
+  The return value of the task. If the task has not finished, it will throw `Timothy.FrameRateTask.TaskNotFinishedException`.
 
 + `public bool AllowTimeExceed { get; init; }`
 
-  > Whether the engine allow time exceeding. `true` fir default. Details are under `MaxTolerantTimeExceedCount`.
-  >
-  > 是否允许执行超时。默认为 `true`。详情参见 `MaxTolerantTimeExceedCount`。
+  Whether the engine allows time exceeding, `true` for default. See more details under `MaxTolerantTimeExceedCount`.
 
 + `public Action<bool> TimeExceedAction { get; init; }`
 
-  > It will be called when time exceeds. Details are under `MaxTolerantTimeExceedCount`.
-  >
-  > 将在超时后被调用。详情参见 `MaxTolerantTimeExceedCount`。
+  It will be called when time exceeds. See more details under `MaxTolerantTimeExceedCount`.
 
 + `public ulong MaxTolerantTimeExceedCount { get; init; }`
 
-  > The maximum number of time exceeding in a series. `5` for default. Once time exceeds, if the number of time exceeding in a series is no more than `MaxTolerantTimeExceedCount`, `TimeExceedAction` will be called with argument `false`, otherwise, if `AllowTimeExceed` is set `true`, `TimeExceedAction` will be called with argument `true`, otherwise (`AllowTimeExceed` is set `false`), it will throw an exception.
-  >
-  > Once more than `MaxTolerantTimeExceedCount`, it will automatically abandon unfinished loops, and reset the loop counter. There is an example about this in the project Test, that is, `Demo5` method.
-  >
-  > 允许连续超时的最大次数。默认为 `5`。一旦某次循环执行超时，如果连续超时次数不超过 `MaxTolerantTimeExceedCount`，`TimeExceedAction` 会被调用，且参数为 `false`；否则，如果 `AllowTimeExceed` 为 `true`，`TimeExceedAction` 会被调用，且参数为 `true`；如果 `AllowTimeExceed` 为 `false`，将会抛出异常。
-  >
-  > 一旦连续超时的次数大于 `MaxTolerantTimeExceedCount`，未完成的循环将会被舍弃，并重新进行循环计数。在 Test 项目中有一个关于本条的例子，即 `Demo5` 方法。
+  The maximum number of time exceeding in a series, `5` for default. Once time exceeds, if the number of time exceeding in a series is no more than `MaxTolerantTimeExceedCount`, `TimeExceedAction` will be called with argument `false`。Otherwise, if `AllowTimeExceed` is set `true`, `TimeExceedAction` will be called with argument `true`, otherwise, that is, `AllowTimeExceed` is set `false`, it will throw `Timothy.FrameRateTask.TimeExceedException`.
+
+  Once more than `MaxTolerantTimeExceedCount`, it will automatically abandon unfinished loops, and reset the loop counter. There is an example about this, which is the `Demo5` method in the project `Test`.