Twitter Util 技术文档

1. 安装指南

在您的项目中使用 Twitter Util 前，您需要先将其作为依赖项添加到您的构建配置中。以下是一个使用 SBT (Scala Build Tool) 的例子：

val utilCore = "com.twitter" %% "util-core" % "24.5.0"

确保您的构建工具支持 Maven Central 仓库，因为这是 Twitter Util 发布的地方。

2. 项目的使用说明

Twitter Util 提供了许多 idiomatic、小型且通用的工具。以下是一些主要功能的使用说明：

单位转换

时间

import com.twitter.conversions.DurationOps._

val duration1 = 1.second
val duration2 = 2.minutes
println(duration1.inMillis) // 输出：1000

空间

import com.twitter.conversions.StorageUnitOps._
val amount = 8.megabytes
println(amount.inBytes) // 输出：8388608
println(amount.inKilobytes) // 输出：8192

Futures

Twitter Util 提供了一个非演员 (non-actor) 的 Scala Futures 实现。

import com.twitter.conversions.DurationOps._
import com.twitter.util.{Await, Future, Promise}

val f = new Promise[Int]
val g = f.map { result => result + 1 }
f.setValue(1)
println(Await.result(g, 1.second)) // 输出：2

// 另一个选项：
g.onSuccess { result =>
  println(result) // 输出：2
}

// 使用 for 表达式：
val xFuture = Future(1)
val yFuture = Future(2)

for {
  x <- xFuture
  y <- yFuture
} {
  println(x + y) // 输出：3
}

对象池

对象池的顺序是先进先出 (FIFO)。

常量对象池

import scala.collection.mutable
import com.twitter.util.{Await, SimplePool}

val queue = new mutable.Queue[Int] ++ List(1, 2, 3)
val pool = new SimplePool(queue)

// 注意：池返回的是 Futures，不会在耗尽时阻塞。
println(Await.result(pool.reserve())) // 输出：1
pool.reserve().onSuccess { item =>
  println(item) // 输出：2
}

动态创建的对象池

这里有一个生成偶数的对象池，它一次存储 4 个数字：

import com.twitter.util.{Future, FactoryPool}

val pool = new FactoryPool[Int](4) {
  var count = 0
  def makeItem() = { count += 1; Future(count) }
  def isHealthy(i: Int) = i % 2 == 0
}

在成功预留一个对象时，它将检查对象的健康状态。

哈希

util-hashing 是一组哈希函数和哈希分布器（例如 ketama）。

使用哈希函数

import com.twitter.hashing.KeyHasher

KeyHasher.FNV1_32.hashKey("string".getBytes)

以下是可用的哈希函数列表：

FNV1_32
FNV1A_32
FNV1_64
FNV1A_64
KETAMA
CRC32_ITU
HSIEH

使用 KetamaDistributor

import com.twitter.hashing.{KetamaDistributor, KetamaNode, KeyHasher}

val nodes = List(KetamaNode("host:port", 1 /* 权重 */, "foo" /* 句柄 */))
val distributor = new KetamaDistributor(nodes, 1 /* 复制数 */)
println(distributor.nodeForHash("abc".##)) // 输出：client

时间和持续期

与双精度浮点数运算类似，Time 和 Duration 的运算现在不会溢出。相反，它们会溢出到 Top 和 Bottom 值，分别类似于正无穷和负无穷。

由于 Time.now 的分辨率降低（并且由于使用系统时间而变得更加昂贵），引入了新的 Stopwatch API 以计算时间间隔。

它的使用非常简单：

import com.twitter.util.{Duration, Stopwatch}
val elapsed: () => Duration = Stopwatch.start()

然后通过应用 elapsed 来读取：

val duration: Duration = elapsed()

3. 项目API使用文档

Twitter Util 的 API 文档可以在其 Scaladoc 中找到。具体的文档可以在 这里 查看。由于文档链接的存在，这里不提供具体的API使用示例。

4. 项目安装方式

Twitter Util 可以通过 Maven Central 仓库进行安装。您需要在项目的 build.sbt 文件中添加以下依赖项：

libraryDependencies += "com.twitter" %% "util-core" % "24.5.0"

确保您的构建工具配置了 Maven Central 仓库。在大多数情况下，这是默认配置的。