Spread C API 简介 - mesadb/mesadb.github.io GitHub Wiki
SP 函数介绍
- SP connect
include sp.h
int SP connect( const char * spread name, const char * private name,
int priority, int group membership, mailbox * mbox,
char * private group );
SP connect 是一个初始化调用，一个应用必须用Spread daemon建立一个连接。所有其他的Spread调用必须引用一个有效的 mbox 集合(mbox 通过引用传递过来). 参数 spread name 是连接到Spread daemon的名称, 它是如下形式的字符串:
-
4803 — 使用 Unix Socket 连接到本地主机的Spread daemon,在/tmp/4803文件夹下. 此形式不能用于连接 Windows95/NT的主机.
-
4803@localhost — 通过loopback接口,在本地主机的4803端口上连接Spread daemon. 此形式可以用于连接 Windows95/NT的主机.
-
[email protected] — 连接到域名“host.domain.edu”和端口4803的主机.
-
[email protected] — 连接到 IP 地址“x.y.221.99” 和端口4803的主机.
SP connect函数的其他参数介绍如下:
| private name | 是连接想要对外宣称的名称.此名称在运行 spread daemon 的主机上必须是唯一的.此名称和 group name 有相同的字符限制(可能不会包含 ’#’ 字符). |
| priority | 是一个 0/1 标识符, 判断连接是否是一个 ”Priority” 连接. 当前,这个是没有影响的. |
| group membership | 是一个布尔整数. 如果设置为1, 然后应用将接受group membership消息, 如果设置为0, 然后应用不接受任何的成员关系的变化消息. |
| mbox | 是一个mailbox变量的指针.在 SP 连接调用返回之后,此变量将为连接持有mbox. |
| private group | 将是一个字符指针,足够大能够持有MAX GROUP NAME字符. 在 SP 连接调用返回之后, 它将包含连接的private group 名称. group 名称能够被用于发送单播消息到此连接,同时没有成员能够加入到这个特定的组. |
此方法的返回值如下:
| 返回值 | 描述 |
| ACCEPT SESSION | 成功 |
| ILLEGAL SPREAD | 给定的spread name连接由于某种原因是非法的. 经常因为在 Windows95/NT 平台上创建一个 Unix 连接, 或者是一个主机或端口号的错误格式. |
| COULD NOT CONNECT | 允许一个到特定 spread daemon 的底层 socket 调用失败. |
| CONNECTION CLOSED | 在通信过程中, 建立连接发生错误或设置没有完成. |
| REJECT VERSION | daemon 或 library 的版本不匹配. |
| REJECT NO NAME | 没有提供用户的private name. |
| REJECT ILLEGAL NAME | 提供的 name 没有满足某些需求 (长度或使用了非法字符) |
| REJECT NOT UNIQUE | 提供的 name 在 daemon 中并不是唯一的. 推荐使用不同的 name. |
- SP disconnect
#include sp.h
int SP disconnect( mailbox mbox );
SP disconnect 当应用结束与 spread daemon 的连接时,此函数将被调用. 应用由可能由其他的到 daemon 的连接,也可能在断开连接之后开启一个新的连接.
SP disconnect函数的参数介绍如下:
| mbox | 参数为你想要断开的连接. |
此方法的返回值如下:
| NORMAL | 成功时,返回0. |
| ILLEGAL SESSION | 当 session 给定的 mbox 不是一个有效连接时,返回. |
- SP join
#include sp.h
int SP join( mailbox mbox , const char * group );
SP join 此方法用于加入一个群组. 如果群组在创建的Spread daemons之中不存在,则重新创建一个, 如果存在,则加入现有的群组.
SP join函数的参数介绍如下:
| mbox | 参数为加入这个群组的连接. |
| group | 参数为加入群组的名称. |
此方法的返回值如下:
| NORMAL | 成功时,返回0. |
| ILLEGAL GROUP | 给定加入的群组由于某种原因是非法的. 通常是由于length = 0 或 length > MAX GROUP NAME. |
| ILLEGAL SESSION | 通过 mbox 指定的 session 是非法的. 通常是由于 seesion 没有激活. |
| CONNECTION CLOSED | 在通信过程中发生错误. join 不能够被初始化. |
*SP leave
#include sp.h
int SP leave( mailbox mbox, const char * group );
SP leave 离开所指定的群组. 如果此群组在 Spread daemons 之中不存在,则此操作会被忽略.
SP leave函数的参数介绍如下:
| mbox | 代表离开群组的连接. |
| group | 代表所离开的群组. |
此方法的返回值如下:
| NORMAL | 成功时,返回0. |
| ILLEGAL SSESION | . |
| NORMAL | 通过 mbox 指定的 session 是非法的. 通常是由于 seesion 没有激活. |
| CONNECTION CLOSED | 在通信过程中发生错误. join 不能够被初始化. |
*SP multicast and family
#include sp.h
int SP multicast(mailbox mbox, service service type, const char * group, int16 mess type, int mess len, const char * mess );
int SP scat multicast( mailbox mbox, service service type, const char * group, int16 mess type, const scatter scat mess );
int SP multigroup multicast(mailbox mbox , service service type, int num groups , const char groups[][MAX GROUP NAME], int16 mess type, int mess len, const char * mess );
int SP multigroup scat multicast(mailbox mbox, service service type, int num groups, const char groups[][MAX GROUP NAME], int16 mess type, const scatter scat mess );
SP multicast 及其变种都能够发送消息到一个或多个群组.消息在特定的连接上发送,同时被标记.服务类型是一个类型域,将被设置为消息所需要的服务类型. 消息的有效标识是:
• UNRELIABLE MESS
• RELIABLE MESS
• FIFO MESS
• CAUSAL MESS
• AGREED MESS
• SAFE MESS
此类型可以是带有其他标识,如SELF DISCARD的 bit ORed. 当前SELF DISCARD 是唯一的额外标识符.
如果SP multicast 或 SP scat multicast 版本正在被使用,而只有一个群组能够被发送. 因此 group string 将包含发送到的group name. 如果一个 multigroup 变种被使用, 然后群组将通过groups integer和group names的列表(消息发送到的所有群组)来指定. 群组名称列表的数量至少要和’num groups’的数量一样多.
Spread system一次只发送一个消息,但这个消息将发给所有的连接,这些连接至少加入了一个列表列出的群组.
消息类型是一个short int (16 bits),可以被应用任意地使用. 目的是它能够被用在不同消息类型的 NAME 上,这样它们是差异化的,不需要进入到消息体. 这个值被接收之前会进行乱序重排矫正.
如果使用 non-scatter 变体, 则一个 single buffer 被传递到多播调用,指定一个 full message 被发送出去. 消息的len field 给粗了消息的字节长度. 而消息域是一个到包含消息的 buffer 的指针. 对于一个 scatter 调用, 所有这些用一个pointer、scat mess来替换 到一个 scatter 结构, 这个结构类似于 iovec. 这个允许消息被发送,不需要支持scatter-gather的系统额外的拷贝开销.
此方法的返回值如下:
| NORMAL | 发送成功的 byte 数. |
| ILLEGAL SESSION | 给定的mbox到多播是违法的. |
| ILLEGAL MESSAGE | message 由一个违法的结构,例如一个 scatter 并没有正确填充. |
| CONNECTION CLOSED | 在通信过程中,发送消息时出现错误,同时发送不能够完成. |
*SP receive and SP scat receive
#include sp.h
int SP receive( mailbox mbox, service * service type, char sender[MAX GROUP NAME], int max groups, int * num groups, char groups[][MAX GROUP NAME], int16 * mess type, int * endian mismatch, int max mess len, char * mess );
int SP scat receive( mailbox mbox, service * service type, char sender[MAX GROUP NAME], int max groups, int * num groups, char groups[][MAX GROUP NAME], int16 * mess type, int * endian mismatch, scatter * scat mess );
SP receive 在Spread toolkit中主要功能是接收函数. 此函数不仅接收数据消息, 也接收成员关系的消息. 加入群组的连接的消息将达到同一个 mailbox,而SP receive 的调用将获得一个来自于群组的单个消息.在接受完成之后,域的数量将被发送到此值, 关于消息的元信息(群组,消息类型,字节顺序).
此函数在Spread中是最复杂的,因为它是系统唯一的方法,返回信息到应用.很多域的变化依赖于消息是否是一个数据结构或一个成员关系消息.
SP receive 函数如果没有消息达到则被阻塞.mbox 给定哪个连接来接收一个消息. 服务类型是一个到不同服务类型的指针,这个服务将被设置为接收消息的消息类型. 消息类型是一个REG MESSAGE 或者 MEMBERSHIP MESS, 或某种指定的类型.
参数的剩下部分是不同的,依赖于服务的类型. 如果服务类型是 REG MESSAGE (i.e. 数据消息) 然后:
| sender | 一个到数组列表的指针,至少 MAX GROUP NAME 大小. 这将被设置为发送连接的名称(它的 private group 名称). |
| max groups | 你已经分配空间的最大群组数.在群组中,数组被传递到receive 函数. |
| num groups | 在群组列表中设置为群组数的指针. |
| groups | 数组赋值为max groups 的组名,每个组名是一个MAX GROUP NAME的字符串. 如果数组不是太小,接收此消息的所有组将被列出,当你调用SP receive时,你已经通过在service type域中设置标识符,来选择DROP RECV语意.在这种情况下,尽可能多的合适群组名称将被列出,同时num groups 值将被设置为负数.例如，如果你的群组列表能够保存5个组名称,但是一个7个群组的消息到来,前5个群组名称将出现在群组列表中,同时num groups将被设置为7. |
| mess type | 设置为消息类型域,应用带有原有消息发送,这只是一个short int (16bits).此值在应用接收之前,已经进行了正确排序. |
| endian mismatch | 设置为true(1)，如果发送主机的排序与接收主机的顺序不同.否则设置为 false(0).此值域以特定的方式来处理,当特定的错误被返回. |
| mess | 接收的实际消息体,被保存在 buffer 中. |
| max mess len | 消息 buffer 的字节长度. 如果消息较大, buffer 大小以通常的方式来处理. |
如果SP_scat_receive函数被使用,而不是SP_receive函数,然后 mess 和 max_mess_len域通过单 scat_mess scatter 结构来替换. scatter将被初始化包含无论什么你想要接受的 buffer 和buffer 的长度.这些 buffers 必须是有效的内存区域.它们将通过receive调用,按照列表的顺序被填充,
如果这是一个MEMB MESSAGE (i.e. 成员消息) ,同时这是一个特殊的 TRANS MESS类型的 membership 消息:
| sender | 当群组中成员关系发生变化时,设置群组的名称. |
| max groups | 不被使用. |
| max mess len | 不被使用. |
| num groups | 经常被设置为 0. |
| groups | 为空,对于一个过渡的成员关系,没有正常的群组. 相反,使用sender域. |
| mess type | 设置为 -1. |
| endian mismatch | 设置为 0, 当转换没有任何排序问题时. |
| mess | 为空. |
因此,你获得唯一信息是 sender 域, 被设置成 group name ,此 group name 接受一个过渡的成员变化消息. TRANS_MEMB_MESS 告诉应用所有的消息在它之后和在REG MEMB MESS 之前将被接收, 这是一个 ’clean up’ 消息将消息置于一个一致状态, 在真正改变成员关系之前. 更多详细介绍请查看相关研究论文.
如果这是一个 MEMB_MESSAGE (i.e. membership message) 和是一个特殊的 REG_MEMB_MESS 类型 membership message:
| sender | 设置到群组名称,此群组正在发生成员关系变化. |
| max groups | 与正常消息相同. |
| max mess len | 与正常消息相同. |
| mess type | 在群组成员的列表中,被设置为此进程的索引. |
| endian mismatch | 设置为 0 ,带有正常成员关系, 没有排序的问题. |
| num groups | 在成员关系变更之后,设置群组中成员的数量. |
| groups | 包含private group names的排序列表,在成员关系发生变化之后. |
| mess | 包含此群组成员关系的标识符,和所有 private group names的列表,这些进程将从老的成员列表更新为新的成员列表. |
data buffer 将包括如下确定长度的域:
*group id;
*int num members;
*char trans members[][MAX GROUP NAME];
群组列表将有成员数量, 每个成员名称都是确定长度的字符. 群组数组的内容依赖于成员关系变化的类型:
*CAUSED BY JOIN: 过渡成员包含加入进程的私有群组.
*CAUSED BY LEAVE: 过渡成员包含离开进程的私有群组.
*CAUSED BY DISCONNECT: 过渡成员包含断开进程的私有群组.
*CAUSED BY NETWORK:过渡成员包含新成员关系的成员群组名.当然所有新的成员都与SP_receive 调用的群组参数来比较.
如果这是一个MEMB MESSAGE ,同时它既不是 REG MEMB MESS 也不是 TRANS MEMB MESS, 它准确地代表这种状态:接收此消息的成员离开群组,同时也是一个通告:当离开发生时,有时被称为”自离开”消息.TRANS MEMB MESS 也绝没有一个CAUSED BY类型,因为它们只服务于通信,直到SAFE 发送和 AGREED 发送 在完全的旧群组成员关系内得到保障.
这个成员离开的群组中的其他成员将接受TRANS MEMB MESS,REG MEMB MESS 消息对儿,来描述以上的成员关系变化.
在自离开的情况下SP_receive 函数域将为如下:
| sender | 设置群组名称,当成员关系发生变化时. |
| max groups | 与正常的消息相同. |
| max mess len | 与正常的消息相同. |
| mess type | 设置为 0. |
| endian mismatch | 设置为 0. |
| num groups | 设置为 0. |
| groups | 将要为空. 这是因为此进程不再是群组的一部分, 不需要再知道群组的信息. |
| mess | 包含了新成员关系的group id,和留下来的成员 private group name.这个名称常常是接受此消息的连接的private group name. |
data buffer 将包括如下确定长度的域:
* group id;
* int num members;
* char trans members[][MAX GROUP NAME];
过渡成员列表将有1个群组名称,包含了离开进程的private group name,这种情况只发生在CAUSED BY LEAVE成员关系变化的情况.
| NORMAL | 接收成功之后返回一个消息大小. |
| ILLEGAL SESSION | 给定接收的mbox是非法的. |
| ILLEGAL MESSAGE | 消息由一个非法的结构,如一个 scatter 没有正确地填充. |
| CONNECTION CLOSED | 在通信过程中接收消息通信错误,同时接收没有完成. |
| BUFFER TOO SHORT | 消息体 buffer 太短,不能放入接受的消息. |
| GROUPS TOO SHORT | 群组 buffer 太短,不能放入群组列表或者接受的成员列表. |
- SP_equal_group_ids
#include sp.h
int SP equal group ids( group id g1, group id g2 );
SP equal group ids 提供了一种方式在成员关系消息上比较两个group ids. group id 通常被用于作为成员关系视图的标识符,与其他的group ids来进行比较.