概述

Water 是一个提供类似网络通信结构的库。它旨在取代通道。它允许你创建一个用于通信的本地网络，如果你希望将你的本地网络加入另一个远程网络（无论是同一台机器还是通过网络远程机器），你也可以做到这一点。它还可以仅用于在两个线程之间通信！

这个项目是因为处理多个通道以实现线程之间复杂互连的需求而产生的。我发现，如果我能使用一个对象的单个实例与多个其他线程通信，将消息呈现给多个接收者但只有一个接收消息的能力，以及能够在相同的管道中发送不同类型的能力，并且能够分段和优先处理，以及能够在多个通信管道上等待，这将变得更加简单。

端点是消息的接收者和发送者，存在于特定的网络中。每个网络有一个ID，每个端点有一个ID。这意味着你可以指定

• 特定网络上的特定端点
• 所有网络上的特定端点
• 特定网络上的任何端点
• 任何网络上的任何端点

一些用途

• 同一台机器上的两个进程进行通信
• 不同机器上的两个进程进行通信（通过网络）
• 线程之间的进程内通信（通道）
• 分布式系统软件
• 通道的替代品

与通道相比的一些优势

• 比多个通道管理单个端点更简单、更易于管理
• 特殊的同步消息对所有接收者都可用，但只有一个可以接收（使用通道难以实现）
• 使用桥接内置网络通信支持
• 将消息注入到端点中（你可以向同一端点发送一个要接收的消息）
• 可以在多个端点/通道上等待
• 高效地处理同一端点上的不同大小类型，相对于使用枚举的通道

相对于通道的一些缺点

• 由于提供了功能，所以比通道多了点代码，但并不多
• 由于需要指定目的地，消息发送更复杂（尽管对于简单情况可以忽略）

一些计划中的功能

• 消息优先级（高优先级先于低优先级处理）（也适用于满端点队列的回退）
• 有关其他与开发相关的事宜，请查看GitHub问题

使用

您可以通过三种方式使用此库。您可以使用Cargo，手动构建，或将其嵌入到自己的代码中。然而，如果您不使用Cargo，则可以手动构建它，最后将其嵌入到源代码中。

如果您是Cargo的新手，请阅读http://doc.crates.io/guide.html。使用Cargo使用最新版本的water库的最简单方法是在您的Cargo.toml中添加以下行

[dependencies.water]

这将导致Cargo下载并设置water库，然后可以使用extern crate water使用它。要查看示例程序，请查看下面的异步发送和同步接收示例部分。

一个Cargo.toml的示例是

[package]
name = "hello"
version = "0.0.1"
authors = ["My Name"]
[dependencies.water]

包含Cargo.toml的当前目录应包含./src/main.rs，您可以将示例代码放入其中，然后键入cargo build来生成程序。另外，请参阅Cargo指南！别忘了查看下面的示例程序，因为它显示了使用库的基本功能的示例。

要手动构建（不使用Cargo），只需克隆此存储库，然后使用以下命令构建：rustc --crate-type rlib ./src/lib.rs -o libwater.rlib。然后，在当前目录中，您可以使用以下命令构建程序：rustc mymain.rs -L .。如果库在另一个目录中，请将-L <path>更改为反映这一点。

我推荐使用Cargo，因为它使管理和构建依赖关系变得非常容易！

要查看更多示例，请查看源树中的tests目录！每个测试将展示库的不同部分以及如何使用它。我的目标是让master分支上的所有内容都正常工作并编译。如果您想要最新的版本，可以选择dev分支或任何其他分支，以找到较少的测试但可能更新功能。

文档

您可以在http://kmcg3413.net/water.rs/doc/lib/找到一些文档。这些文档应与master分支和https://crates.io/water存储库保持同步。您还可以通过克隆此存储库并执行rustdoc ./src/lib.rs在本地生成文档，这将创建一个包含HTML文档的doc子目录。