按照文件大小自动划分文件文档完善

README.en.md

@@ -12,6 +12,7 @@
 * Enable or disable Logger, you can disable or switch to a higher level in your production environment
 * Log file supports, and you can customer the name of your log file.
 * Duration rolling supports, which means it will roll to a new log file by duration automatically, such as one day one log file.
+* File size rolling supports, which means it will roll to a new log file by file size automatically, such as one 64 MB one log file.
 
 _Check [HISTORY.md](./HISTORY.md) and [FUTURE.md](./FUTURE.md) to get more information._
 
@@ -75,6 +76,7 @@ func main() {
 * [enable_disable](./_examples/enable_disable.go)
 * [change_log_level](./_examples/change_log_level.go)
 * [log_to_file](./_examples/log_to_file.go)
+* [wrapper](./_examples/wrapper.go)
 
 _Check more examples in [_examples](./_examples)._
 

README.md

@@ -11,7 +11,8 @@
 * 支持日志级别控制，目前一共有四个日志级别
 * 支持开启或者关闭日志功能，线上环境可以关闭或调高日志级别
 * 支持记录日志到文件中，自定义日志文件名
-* 支持按照时间间隔进行自动划分日志文件，比如按天划分日志文件
+* 支持按照时间间隔进行自动划分日志文件，比如每一天划分一个日志文件
+* 支持按照文件大小进行自动划分日志文件，比如每 64 MB 划分一个日志文件
 
 _历史版本的特性请查看 [HISTORY.md](./HISTORY.md)。未来版本的新特性和计划请查看 [FUTURE.md](./FUTURE.md)。_
 
@@ -75,6 +76,7 @@ func main() {
 * [enable_disable](./_examples/enable_disable.go)
 * [change_log_level](./_examples/change_log_level.go)
 * [log_to_file](./_examples/log_to_file.go)
+* [wrapper](./_examples/wrapper.go)
 
 _更多使用案例请查看 [_examples](./_examples) 目录。_
 

_examples/wrapper.go

@@ -0,0 +1,48 @@
+// Copyright 2020 Ye Zi Jie. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Author: fish
+// Email: [email protected]
+// Created at 2020/03/05 17:30:21
+
+package main
+
+import (
+    "time"
+
+    "github.com/FishGoddess/logit/wrapper"
+)
+
+func main() {
+
+    // 1. DurationRollingFile is a time sensitive file.
+    durationRollingFile := wrapper.NewDurationRollingFile(24*time.Hour, func(now time.Time) string {
+        return "D:/" + now.Format("20060102-150405") + ".txt"
+    })
+    defer durationRollingFile.Close()
+
+    // You can use it like using os.File!
+    durationRollingFile.Write([]byte("Hello!"))
+
+    // =================================================================================
+
+    // 2. SizeRollingFile is a file size sensitive file.
+    sizeRollingFile := wrapper.NewSizeRollingFile(64*wrapper.KB, func(now time.Time) string {
+        return "D:/" + now.Format("20060102150405.000") + ".log"
+    })
+    defer sizeRollingFile.Close()
+
+    // You can use it like using os.File!
+    sizeRollingFile.Write([]byte("Hello!"))
+}

wrapper/doc.go

@@ -23,12 +23,23 @@ Package wrapper provides some writers to extend your Logger.
 
     // DurationRollingFile is a time sensitive file.
     file := NewDurationRollingFile(24 * time.Hour, func(now time.Time) string {
-        return "D:/" + currentTime.Format("20060102-150405") + ".txt"
+        return "D:/" + now.Format("20060102-150405") + ".txt"
     })
     defer file.Close()
 
     // You can use it like using os.File!
-    file.Write([]byte("Hello!")
+    file.Write([]byte("Hello!"))
+
+2. SizeRollingFile:
+
+    // SizeRollingFile is a file size sensitive file.
+    file := NewSizeRollingFile(64*KB, func (now time.Time) string {
+        return "D:/" + now.Format("20060102150405.000") + ".log"
+    })
+    defer file.Close()
+
+    // You can use it like using os.File!
+    file.Write([]byte("Hello!"))
 
 */
 package wrapper // import "github.com/FishGoddess/logit/wrapper"

wrapper/duration_rolling_file.go

@@ -42,7 +42,7 @@ type DurationRollingFile struct {
     // lastTime is the created time of current file above.
     lastTime time.Time
 
-    // duration is the core property of this struct.
+    // duration is the core field of this struct.
     // Every times currentTime - lastTime >= duration, the file will
     // roll to an entire new file for writing.
     // Notice that its min value is one Second. See minDuration.

wrapper/size_rolling_file.go

@@ -25,24 +25,40 @@ import (
     "time"
 )
 
-// SizeRollingFile 是按照文件大小自动划分的文件类型
+// SizeRollingFile is a file size sensitive file.
+//
+//  file := NewSizeRollingFile(64*KB, func (now time.Time) string {
+//      return "D:/" + now.Format("20060102150405.000") + ".log"
+//  })
+//  defer file.Close()
+//  file.Write([]byte("Hello!"))
+//
+// You can use it like using os.File!
 type SizeRollingFile struct {
 
     // file points the writer which will be used this moment.
     file *os.File
 
-    // limitedSize 是指这个文件限制的大小，达到这个大小之后就会自动划分为另一个文件
-    // 注意：出于对写操作的性能优化，采取了自计数方式的设计方案，参考 currentSize
+    // limitedSize is the limited size of this file.
+    // File will roll to next file if its size reaches limitedSize.
+    // This field should be always larger than minLimitedSize for some safe considerations.
+    // Notice that it doesn't mean every files must be this size due to our performance optimization
+    // scheme. Generally it equals to file size, however, it will not equal to file size
+    // if someone modified this file. See currentSize.
     limitedSize int64
 
-    // currentSize 表示当前文件大小
-    // 由于每一次写操作都需要获取文件大小，这样会发起一次系统调用，file.Stat() 非常耗时
-    // 这里将文件大小记录起来，每一次写操作直接使用这个大小进行判断
-    // 这在没有外界修改过文件的情况下一般是没有问题的，而且能提高性能
-    // 只有当判断到 currentSize >= limitedSize 的时候，才进行一次系统调用查询真实的文件大小
-    // 如果真实的文件大小大于 currentSize，此时需要划分文件，并设置 currentSize 为 0
-    // 如果真实的文件大小小于 currentSize，重新设置 currentSize，此时不划分文件
-    // 注意：这个设计方案可以保证文件不小于 limitedSize 的大小
+    // currentSize equals to the size of current file.
+    // If current file have changed, currentSize will reset to 0.
+    // The reason why we set this field is file.Stat() is too expensive!
+    // Every writing operations will fetch file size, that means each operation
+    // will call file.Stat() for size. It's not a good way to fetch file size.
+    // So we keep one field inside, and record current size of current file with it.
+    // Each time fetching file size, the only thing wo do is checking this field.
+    // This way is cheaper, even cheapest. Of course, we should maintain this field
+    // inside for precision. Also, it doesn't mean we won't call file.Stat() anymore.
+    // If currentSize >= limitedSize, we will still call file.Stat() for precision.
+    // Certainly, we will set currentSize to the real size of file. Hey, you know we
+    // won't waste the time we spent on file.Stat() ^_^.
     currentSize int64
 
     // nextFilename is a function for generating a new file name.