GoldFlake：API使用文档

1. 前言：

  因为是自己造的 GoldFlake，那就只能自己来写官方文档了！💪💪（可恶明明是一个没人用的东西还做这么多工作！）

---

2. 导入 GoldFlake

  首先请确保配置好了 golang 环境，在终端输入如下命令即可自动导入：

go get github.com/ncghost1/GoldFlake

  附赠 github 链接：https://github.com/ncghost1/GoldFlake

---

3. API

InitGfNode

func InitGfNode(workerid uint32) (*GoldFlake, error)

  使用 InifGfNode 初始化一个 GoldFlake 结构体。

  传入参数 workerid 是机器id，初始化时 GoldFlake 结构体中 workerid 成员被传入参数给赋值，其余成员为默认值。

---

InitRandProcess

func InitRandProcess(Size uint32, Mode int8) error 

  使用 InitRandProcess 初始化全局变量 RVStack。

  传入参数 Size 赋值给 RVStack 的成员 Size，即 RVStack 的可用空间大小。

  传入参数 Mode 会影响 RVStack 的标志位，用于确定生成随机数方式。

  返回值为一个 error 类型变量，在 Size 或 Mode 不合法时返回错误信息。

  RVStack 是一个 RandValStack 结构体，用于装载与弹出随机毫秒时间偏移值，运作原理是一个模拟栈。

---

RandProcess

func RandProcess(chanceNumerator, chanceDenominator, maxTimeOffset uint64) (int8, error)

  使用 RandProcess 生成随机毫秒时间偏移量，若 RVStack 未满则将其填充。使用时请独立创建一个 goroutine 来与生成id异步持续运行。

  传入参数 chanceNumerator 为概率分子。

  传入参数 chanceDenominator 为概率分母，与 chanceNumerator 以分数形式表示获取随机毫秒时间偏移量的概率。

  传入参数 maxTimeOffset 为最大毫秒时间偏移量，用来确定获取的随机毫秒时间偏移量的最大范围，获取的随机毫秒时间偏移量的范围为 1~maxTimeOffset。

  返回值为一个状态码（int8）与一个错误信息（error）。状态码用于表示当前 RVStack 的状态，-1 表示标志位出现了错误，0 表示成功执行，1 表示目前无法读写 RVStack，因其被生成id给占用。

// 使用示例：
go func() {
        for {
            status, err := GoldFlake.RandProcess(1, 2, maxTimeOffset)
            if err != nil {
                t.Errorf("RandProcess error:%s", err)
            }
            if status == GoldFlake.RandProcessNotReady {
                runtime.Gosched()
            }
        }
    }()

---

IntervalRandProcess

func IntervalRandProcess(chanceNumerator, chanceDenominator, maxTimeOffset uint64, Interval time.Duration) (int8, error)

  使用 RandProcess 间歇生成随机毫秒时间偏移量，若 RVStack 未满则将其填充。使用时请独立创建一个 goroutine 来与生成id异步持续运行。

  传入参数 chanceNumerator 为概率分子。

  传入参数 chanceDenominator 为概率分母，与 chanceNumerator 以分数形式表示获取随机毫秒时间偏移量的概率。

  传入参数 maxTimeOffset 为最大毫秒时间偏移量，用来确定获取的随机毫秒时间偏移量的最大范围，获取的随机毫秒时间偏移量的范围为 1~maxTimeOffset。

  传入参数 Interval 为执行该函数的时间间隔。

  返回值为一个状态码（int8）与一个错误信息（error）。状态码用于表示当前 RVStack 的状态，-1 表示标志位出现了错误，0 表示成功执行，1 表示目前无法读写 RVStack，因其被生成id给占用。

// 使用示例：
go func() {
        for {
            status, err := GoldFlake.IntervalRandProcess(1, 2, maxTimeOffset, time.Millisecond)
            if err != nil {
                t.Errorf("RandProcess error:%s", err)
            }
            if status == GoldFlake.RandProcessNotReady {
                runtime.Gosched()
            }
        }
    }()

---

Generate

func (gf *GoldFlake) Generate() (uint64, error)

  该方法属于 GoldFlake 结构体，使用 Generate 生成id，支持三种使用方法：

  1.直接使用，即不使用 RVStack 提供随机毫秒时间偏移量，效果等同于传统雪花算法。

  2.与 IntervalRandProcess 一起使用，随机性较差，但性能较高，生成随机毫秒时间偏移量比较随缘，与 OS 和目前运行的进程，硬件等等因素都有关。

  3.与 RandProcess 一起使用，随机性较好，但性能较差，单核与多核运行性能差距明显，需使用双核以上获得最好的性能。

  返回值为一个 id（uint64）和一个错误信息（error）。

// 使用示例
for {
    go func() {
        for {
            status, err := GoldFlake.RandProcess(1, 2, maxtimeoffset)
            if err != nil {
                b.Errorf("RandProcess error:%s", err)
            }
            if status == GoldFlake.RandProcessNotReady {
                runtime.Gosched()
            }
        }
    }()

    // 模拟获取到生成id请求
    if getGenerateIdRequest() != nil {
        uid, err := Gf.Generate()
        if err != nil {
            fmt.Println(err)
            return
        }
        // 模拟回复生成id
        sendGenerateIdResponse(uid)
    }
}

---

SyncGenerateAndRand

func (gf *GoldFlake) SyncGenerateAndRand(chanceNumerator, chanceDenominator, maxTimeOffset uint64) (uint64, error)

  该方法属于 GoldFlake 结构体，使用 SyncGenerateAndRand 生成id，在生成时发现到达新毫秒时间则获取随机毫秒时间偏移量。
  传入参数 chanceNumerator 为概率分子。

  传入参数 chanceDenominator 为概率分母，与 chanceNumerator 以分数形式表示获取随机毫秒时间偏移量的概率。

  传入参数 maxTimeOffset 为最大毫秒时间偏移量，用来确定获取的随机毫秒时间偏移量的最大范围，获取的随机毫秒时间偏移量的范围为 1~maxTimeOffset。

  返回值为一个 id（uint64）和一个错误信息（error）。

// 使用示例
func main() {
    var workerid uint32 = 1
    var stackSize uint32 = 5
    var chanceNumerator uint64 = 1
    var chanceDenominator uint64 = 2
    var maxTimeOffset uint64 = 5
    var Signal int8 = RandProcessSync
    Gf, err := GoldFlake.InitGfNode(workerid)
    if err != nil {
        fmt.Println(err)
        return
    }
    InitRandProcess(stackSize, Signal)
    uid, err := Gf.SyncGenerateAndRand(chanceNumerator, chanceDenominator, maxTimeOffset)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(uid)
}

---