ZeroMQ API(四) 套接字
1、創建一個套接字
1.1 zmq_socket(3)
1.1.1 名稱
zmq_socket - 創建ZMQ套接字
1.1.2 概要
void * zmq_socket(void * context,int type);
1.1.3 描述
zmq_socket()函數將在指定的上下文中創建一個ZMQ套接字,並向新創建的套接字返回一個不透明的句柄。 type參數指定套接字類型,它確定套接字通信的語義。
新創建的套接字最初是未綁定的,並且不與任何端點關聯。為了建立消息流,套接字必須首先使用zmq_connect(3)連接到至少一個端點,或者必須創建至少一個端點以接受與zmq_bind(3)的傳入連接。
1.1.3.1 與傳統套接字的主要區別
一般來說,傳統套接字為面向連接的可靠字節流(SOCK_STREAM)或無連接不可靠數據報(SOCK_DGRAM)提供同步接口。相比之下,ZMQ套接字提供了一個異步消息隊列的抽象,具有確切的排隊語義取決於使用的套接字類型。傳統套接字傳輸字節流或離散數據報時,ZMQ套接字傳輸離散消息。
ZMQ套接字是異步的,意味著物理連接建立和拆除,重新連接和有效傳輸的時間對用戶是透明的,並由ZMQ自己組織。此外,消息可能在對等體不可用以接收它們的情況下排隊。
傳統套接字只允許嚴格的一對一(兩個對等體),多對一(多個客戶機,一個服務器),或者在某些情況下允許一對多(多播)關系。除ZMQ_PAIR之外,ZMQ套接字可以使用zmq_connect()連接到多個端點,同時使用zmq_bind()接受來自綁定到該套接字的多個端點的傳入連接,從而允許多對多關系。
1.1.3.2 線程安全
ZMQ套接字不是線程安全的。應用程序絕不能使用來自多個線程的套接字,除非在將套接字從一個線程遷移到另一個線程的情況下具有“完全圍柵”內存屏障。
1.1.3.3 套接字類型
以下部分介紹由ZMQ定義的套接字類型,按照由相關套接字類型構建的常規消息傳遞模式進行分組。
1.1.3.3.1 請求 - 回復模式
請求 - 應答模式用於從ZMQ_REQ客戶端向一個或多個ZMQ_REP服務發送請求,並接收對發送的每個請求的後續回復。請求 - 答復模式由http://rfc.zeromq.org/spec:28正式定義。
ZMQ_REQ
客戶端使用ZMQ_REQ類型的套接字向服務發送請求並從服務接收回復。 此套接字類型只允許交換zmq_send(請求)和隨後的zmq_recv(應答)調用序列。 發送的每個請求都是在所有服務中進行的,並且每個收到的回復都與上次發出的請求相匹配。
如果沒有可用的服務,則套接字上的任何發送操作都應阻塞,直到至少有一項服務可用。 REQ套接字不應丟棄消息。
ZMQ_REQ特性總結
ZMQ_REP 兼容的對等套接字 ZMQ_REP,ZMQ_ROUTER
方向 雙向
發送/接收模式 發送,接收,發送,接收,...
出路由策略 循環
傳入路由策略 最後一個peer
靜音狀態下的動作 Block
ZMQ_REP
服務使用類型為ZMQ_REP的套接字接收來自客戶端的請求並將其發送給客戶端。 此套接字類型只允許交換zmq_recv(請求)和隨後的zmq_send(回復)調用序列。 收到的每個請求均從所有客戶端公平排隊,並且每個發送的回復都路由到發出最後請求的客戶端。 如果原始請求者不再存在,則回復將被無聲丟棄。
ZMQ_REP特性總結
兼容的對等套接字 ZMQ_REQ,ZMQ_DEALER
方向 雙向
發送/接收模式 接收,發送,接收,發送,...
傳入路由策略 公平排隊
外出路由策略 最後一個同伴
ZMQ_DEALER
ZMQ_DEALER類型的套接字是用於擴展請求/回復套接字的高級模式。 發送的每條消息在所有連接的對等體中都是全局消息傳遞的,並且每個收到的消息都從所有連接的對等體公平排隊。
當ZMQ_DEALER套接字由於達到所有對等體的高水位而進入靜音狀態或者根本沒有對等體時,套接字上的任何zmq_send(3)操作都應阻塞,直到靜音狀態結束或至少一個 對等體可用於發送; 消息不會被丟棄。
當一個ZMQ_DEALER套接字連接到一個ZMQ_REP套接字時,每個發送的消息必須包含一個空的消息部分,分隔符,後跟一個或多個正文部分。
ZMQ_DEALER特性摘要
兼容的對等套接字 ZMQ_ROUTER,ZMQ_REP,ZMQ_DEALER
方向 雙向
發送/接收模式 不受限制
出路由策略 循環
傳入路由策略 公平排隊
靜音狀態下的動作 Block
ZMQ_ROUTER
ZMQ_ROUTER類型的套接字是用於擴展請求/回復套接字的高級套接字類型。當接收到消息時,ZMQ_ROUTER套接字在將消息傳遞給應用程序之前,應該將包含消息始發節點身份的消息部分添加到消息中。收到的消息從所有連接的對等體中公平排隊。發送消息時,ZMQ_ROUTER套接字應刪除消息的第一部分,並用它來確定消息應被路由到的對等體的身份。如果對等體不再存在,默認情況下將默認丟棄該消息,除非ZMQ_ROUTER_MANDATORY套接字選項設置為1。
當ZMQ_ROUTER套接字由於達到所有對等體的高水位而進入靜音狀態時,發送到套接字的任何消息都應該被丟棄,直到靜音狀態結束。同樣,除非設置了ZMQ_ROUTER_MANDATORY套接字選項,否則路由到已達到單個高位標記的對等方的任何消息也將被丟棄。
當一個ZMQ_REQ套接字連接到一個ZMQ_ROUTER套接字時,除了始發節點的身份外,每個收到的消息都應該包含一個空的定界符消息部分。因此,應用程序所看到的每個接收到的消息的整個結構變成:一個或多個標識部分,定界符部分,一個或多個身體部分。當將回復發送到ZMQ_REQ套接字時,應用程序必須包含分隔符部分。
ZMQ_ROUTER特性總結
兼容對等套接字 ZMQ_DEALER,ZMQ_REQ,ZMQ_ROUTER
方向 雙向
發送/接收模式 不受限制
傳出路由策略 查看文本
傳入路由策略 外播隊列
靜音狀態下的動作 丟棄(請參閱文本)
1.1.3.3.2 發布 - 訂閱模式
發布 - 訂閱模式用於以扇出方式從單個發布者到多個訂閱者的一對多數據分發。發布 - 訂閱模式由http://rfc.zeromq.org/spec:29正式定義。
ZMQ_PUB
發布者使用類型為ZMQ_PUB的套接字來分發數據。 發送的消息以扇形方式分發給所有連接的對等體。 此套接字類型未實現zmq_recv(3)函數。
當ZMQ_PUB套接字由於達到用戶的高水位而進入靜音狀態時,任何發送給該用戶的消息都應該被丟棄,直到靜音狀態結束。 zmq_send()函數不會為此套接字類型阻塞。
ZMQ_PUB特性總結
兼容的對等套接字 ZMQ_SUB,ZMQ_XSUB
方向 單向
發送/接收模式 只發送
傳入路由策略 N / A
出路由策略 扇出
在靜音狀態下的動作 丟棄
ZMQ_SUB
用戶使用類型為ZMQ_SUB的套接字訂閱由發布者分發的數據。 最初,ZMQ_SUB套接字未訂閱任何消息,請使用zmq_setsockopt(3)的ZMQ_SUBSCRIBE選項指定要訂閱哪些消息。 此套接字類型未實現zmq_send()函數。
ZMQ_SUB特性摘要
兼容的對等套接字 ZMQ_PUB,ZMQ_XPUB
方向 單向
發送/接收模式 只接收
傳入路由策略 外播隊列
出路由策略 N / A
ZMQ_XPUB
與ZMQ_PUB相同,只不過您可以以傳入消息的形式接收來自對等方的訂閱。 訂閱消息是一個字節1(用於訂閱)或字節0(用於取消訂閱),隨後是訂閱主體。 沒有sub / unsub前綴的郵件也會收到,但對訂閱狀態沒有影響。
ZMQ_XPUB特性總結
兼容的對等套接字 ZMQ_SUB,ZMQ_XSUB
方向 單向
發送/接收模式 發送消息,接收訂閱
傳入路由策略 N / A
出路由策略 扇出
在靜音狀態下的動作 丟棄
ZMQ_XSUB
除了您通過向套接字發送訂閱消息進行訂閱以外,與ZMQ_SUB相同。 訂閱消息是一個字節1(用於訂閱)或字節0(用於取消訂閱),隨後是訂閱主體。 沒有sub / unsub前綴的消息也可能被發送,但對訂閱狀態沒有影響。
ZMQ_XSUB特性摘要
兼容對等套接字 ZMQ_PUB,ZMQ_XPUB
方向 單向
發送/接收模式 接收消息,發送訂閱
傳入路由策略 外播隊列
出路由策略 N / A
在靜音狀態下的動作 丟棄
1.1.3.3.3 管道模式
管道模式用於將數據分配給管道中排列的節點。 數據總是沿著流水線流下,並且流水線的每個階段都連接到至少一個節點。 當一個流水線階段連接到多個節點時,數據在所有連接的節點之間被輪流處理。管道模式由http://rfc.zeromq.org/spec:30正式定義。
ZMQ_PUSH
管道節點使用類型為ZMQ_PUSH的套接字將消息發送到下遊管道節點。 消息對所有連接的下遊節點進行循環處理。 此套接字類型未實現zmq_recv()函數。
當ZMQ_PUSH套接字由於達到所有下遊節點的高水位標記而進入靜音狀態,或者根本沒有下遊節點時,則套接字上的任何zmq_send(3)操作應阻塞,直到靜音狀態結束或在 至少有一個下遊節點可用於發送; 消息不會被丟棄。
ZMQ_PUSH特性總結
兼容的同級插座 ZMQ_PULL
方向 單向
發送/接收模式 只發送
傳入路由策略 N / A
傳出路由策略 循環賽
靜音狀態下的動作 阻塞
ZMQ_PULL
管道節點使用類型為ZMQ_PULL的套接字來接收來自上遊管道節點的消息。 消息從所有連接的上遊節點中公平排隊。 此套接字類型未實現zmq_send()函數。
ZMQ_PULL特性摘要
兼容的對等套接字 ZMQ_PUSH
方向 單向
發送/接收模式 只接收
傳入路由策略 外播隊列
出路由策略 N / A
靜音狀態下的動作 阻塞
1.1.3.3.4 獨家配對模式
獨占配對模式用於將對等體連接到另一個對等體。 這種模式用於inproc傳輸中的線程間通信。排他配對模式由http://rfc.zeromq.org/spec:31正式定義。
ZMQ_PAIR
ZMQ_PAIR類型的套接字只能在任何時候連接到單個對等端。 對通過ZMQ_PAIR套接字發送的消息不執行消息路由或過濾。
當ZMQ_PAIR套接字由於已連接的對等端達到高水位而進入靜音狀態,或者如果沒有對端連接時,則套接字上的任何zmq_send(3)操作都應阻塞,直到對端可用於發送; 消息不會被丟棄。
註:ZMQ_PAIR套接字設計用於跨zmq_inproc(7)傳輸的線程間通信,而不實現自動重新連接等功能。 ZMQ_PAIR套接字被認為是實驗性的,可能有其他缺失或損壞的方面。
ZMQ_PAIR特性總結
兼容的對等套接字 ZMQ_PAIR
方向 雙向
發送/接收模式 不受限制
傳入路由策略 N / A
出路由策略 N / A
靜音狀態下的動作 阻塞
1.1.3.3.5 本機模式
本地模式用於與TCP對等進行通信,並允許在任一方向進行異步請求和回復。
ZMQ_STREAM
當使用tcp:// transport時,使用類型為ZMQ_STREAM的套接字??來發送和接收來自非ZMQ對等體的TCP數據。 ZMQ_STREAM套接字可以作為客戶端和/或服務器,異步地發送和/或接收TCP數據。
當接收到TCP數據時,一個ZMQ_STREAM套接字在將消息傳遞給應用程序之前,應該在消息中預先包含一個消息部分,該消息部分包含源消息的身份。收到的消息從所有連接的對等體中公平排隊。
發送TCP數據時,ZMQ_STREAM套接字應刪除消息的第一部分,並用它來確定消息將被路由到的對等體的身份,而不可路由的消息應引起EHOSTUNREACH或EAGAIN錯誤。
要打開到服務器的連接,請使用zmq_connect調用,然後使用ZMQ_IDENTITY zmq_getsockopt調用獲取套接字標識。
要關閉特定連接,請發送身份證,然後發送零長度消息(請參閱示例部分)。
進行連接時,應用程序將收到一條零長度的消息。同樣,當對端斷開連接(或連接丟失)時,應用程序將收到一個零長度的消息。
數據幀上的ZMQ_SNDMORE標誌被忽略。您必須發送一個身份框架後跟一個數據框。
另外,請註意,省略ZMQ_SNDMORE標誌將阻止在同一套接字上發送更多數據(來自任何客戶端)。
ZMQ_STREAM特性總結
兼容的同級套接字 沒有
方向 雙向
發送/接收模式 不受限制
傳出路由策略 查看文本
傳入路由策略 外播隊列
在靜音狀態 EAGAIN行動
1.1.4 返回值
如果成功,zmq_socket()函數將返回一個不透明的句柄給新創建的套接字。 否則,它將返回NULL並將errno設置為下面定義的值之一。
1.1.5 錯誤
EINVAL:請求的套接字類型無效。
EFAULT:提供的上下文無效。
EMFILE:已達到開放式ZMQ插座總數的限制。
ETERM:指定的上下文已終止。
2、關閉一個套接字
2.1 zmq_close(3)
2.1.1 名稱
zmq_close - 關閉ZMQ套接字
2.1.2 概要
int zmq_close(void * socket);
2.1.3 描述
zmq_close()函數將銷毀由套接字參數引用的套接字。 從網絡物理接收但尚未通過zmq_recv()應用程序接收到的任何未完成消息都將被丟棄。 丟棄應用程序使用zmq_send()發送但尚未物理傳輸到網絡的消息的行為取決於指定套接字的ZMQ_LINGER套接字選項的值。
註:ZMQ_LINGER的默認設置不會丟棄未發送的消息; 此行為可能會導致應用程序在調用zmq_term()時被阻止。 有關詳細信息,請參閱zmq_setsockopt(3)和zmq_term(3)。
2.1.4 返回值
如果成功,zmq_close()函數將返回零。 否則它將返回-1並將errno設置為下面定義的值之一。
2.1.5 錯誤
ENOTSOCK:提供的套接字無效。
3、操作socket選項
3.1 zmq_getsockopt(3)
3.1.1 名稱
zmq_getsockopt - 獲取ZMQ套接字選項
3.1.2 概要
int zmq_getsockopt(void * socket,int option_name,void * option_value,size_t * option_len);
3.1.3 描述
zmq_getsockopt()函數將檢索由socket參數指向的ZMQ套接字的option_name參數指定的選項的值,並將其存儲在option_value參數指向的緩沖區中。 option_len參數是由option_value指向的緩沖區的大小(以字節為單位); 成功完成後,zmq_getsockopt()將修改option_len參數以指示存儲在緩沖區中的選項值的實際大小。
可以使用zmq_getsockopt()函數檢索以下選項:
ZMQ_AFFINITY:檢索I / O線程關聯
ZMQ_BACKLOG:檢索未完成連接隊列的最大長度
ZMQ_CURVE_PUBLICKEY:檢索當前的CURVE公鑰
ZMQ_CURVE_SECRETKEY:檢索當前的CURVE密鑰
ZMQ_CURVE_SERVERKEY:檢索當前的CURVE服務器密鑰
ZMQ_EVENTS:檢索套接字事件狀態
ZMQ_FD:檢索與套接字關聯的文件描述符
ZMQ_GSSAPI_PLAINTEXT:檢索GSSAPI明文或加密狀態
ZMQ_GSSAPI_PRINCIPAL:檢索GSSAPI主體的名稱
ZMQ_GSSAPI_SERVER:檢索當前的GSSAPI服務器角色
ZMQ_GSSAPI_SERVICE_PRINCIPAL:檢索GSSAPI服務主體的名稱
ZMQ_HANDSHAKE_IVL:檢索最大握手時間間隔
ZMQ_IDENTITY:檢索套接字標識
ZMQ_IMMEDIATE:檢索attach-on-connect值
ZMQ_IPV4ONLY:檢索僅限IPv4的套接字覆蓋狀態
ZMQ_IPV6:檢索IPv6套接字狀態
ZMQ_LAST_ENDPOINT:檢索最後一個端點集
ZMQ_LINGER:檢索套接字關閉的持續時間
ZMQ_MAXMSGSIZE:最大可接受的入站消息大小
ZMQ_MECHANISM:檢索當前的安全機制
ZMQ_MULTICAST_HOPS:組播數據包的最大網絡跳數
ZMQ_PLAIN_PASSWORD:檢索當前密碼
ZMQ_PLAIN_SERVER:檢索當前的PLAIN服務器角色
ZMQ_PLAIN_USERNAME:檢索當前PLAIN用戶名
ZMQ_RATE:檢索多播數據速率
ZMQ_RCVBUF:檢索內核接收緩沖區大小
ZMQ_RCVHWM:檢索入站消息的高水位標記
ZMQ_RCVMORE:更多消息數據部分要遵循
ZMQ_RCVTIMEO:套接字操作返回EAGAIN之前的最長時間
ZMQ_RECONNECT_IVL:檢索重新連接間隔
ZMQ_RECONNECT_IVL_MAX:檢索最大重新連接間隔
ZMQ_RECOVERY_IVL:獲取組播恢復間隔
ZMQ_SNDBUF:檢索內核傳輸緩沖區大小
ZMQ_SNDHWM:檢索出站消息的高水位標記
ZMQ_SNDTIMEO:套接字操作返回EAGAIN之前的最長時間
ZMQ_TCP_KEEPALIVE:重寫SO_KEEPALIVE套接字選項
ZMQ_TCP_KEEPALIVE_CNT:覆蓋TCP_KEEPCNT套接字選項
ZMQ_TCP_KEEPALIVE_IDLE:覆蓋TCP_KEEPCNT(或某些操作系統上的TCP_KEEPALIVE)
ZMQ_TCP_KEEPALIVE_INTVL:覆蓋TCP_KEEPINTVL套接字選項
ZMQ_TOS:檢索服務類型套接字覆蓋狀態
ZMQ_TYPE:檢索套接字類型
ZMQ_ZAP_DOMAIN:檢索RFC 27身份驗證域
3.1.4 返回值
如果成功,zmq_getsockopt()函數將返回零。 否則它將返回-1並將errno設置為下面定義的值之一。
3.1.5 錯誤
EINVAL:請求的選項option_name未知,或者請求的option_len或option_value無效,或者由option_len指定的option_value指向的緩沖區的大小不足以存儲選項值。
ETERM:與指定套接字關聯的ZMQ上下文已終止。
ENOTSOCK:提供的套接字無效。
EINTR:信號傳遞中斷了操作。
3.2 zmq_setsockopt(3)
3.2.1 名稱
zmq_setsockopt - 設置ZMQ套接字選項
3.2.2 概要
int zmq_setsockopt(void * socket,int option_name,const void * option_value,size_t option_len);
註意:除ZMQ_SUBSCRIBE,ZMQ_UNSUBSCRIBE,ZMQ_LINGER,ZMQ_ROUTER_HANDOVER,ZMQ_ROUTER_MANDATORY,ZMQ_PROBE_ROUTER,ZMQ_XPUB_VERBOSE,ZMQ_REQ_CORRELATE和ZMQ_REQ_RELAXED之外的所有選項僅對後續的套接字綁定/連接生效。
具體來說,安全選項會在隨後的綁定/連接調用中生效,並且可以隨時進行更改以影響後續的綁定和/或連接。
3.2.3 描述
zmq_setsockopt()函數應將option_name參數指定的選項設置為由socket參數指向的ZMQ套接字的option_value參數指向的值。 option_len參數是選項值的大小(以字節為單位)。
可以使用zmq_setsockopt()函數設置以下套接字選項:
ZMQ_AFFINITY:設置I / O線程關聯
ZMQ_BACKLOG:設置未完成連接隊列的最大長度
ZMQ_CONNECT_RID:分配下一個出站連接ID
ZMQ_CONFLATE:只保留最後一條消息
ZMQ_CURVE_PUBLICKEY:設置CURVE公鑰
ZMQ_CURVE_SECRETKEY:設置CURVE密鑰
ZMQ_CURVE_SERVER:設置CURVE服務器角色
ZMQ_CURVE_SERVERKEY:設置CURVE服務器密鑰
ZMQ_GSSAPI_PLAINTEXT:禁用GSSAPI加密
ZMQ_GSSAPI_PRINCIPAL:設置GSSAPI主體的名稱
ZMQ_GSSAPI_SERVER:設置GSSAPI服務器角色
ZMQ_GSSAPI_SERVICE_PRINCIPAL:設置GSSAPI服務主體的名稱
ZMQ_HANDSHAKE_IVL:設置最大握手時間間隔
ZMQ_IDENTITY:設置套接字標識
ZMQ_IMMEDIATE:僅對已完成的連接排隊消息
ZMQ_IPV6:在套接字上啟用IPv6
ZMQ_LINGER:設置套接字關閉的延遲時間
ZMQ_MAXMSGSIZE:最大可接受的入站消息大小
ZMQ_MULTICAST_HOPS:組播數據包的最大網絡跳數
ZMQ_PLAIN_PASSWORD:設置PLAIN安全密碼
ZMQ_PLAIN_SERVER:設置PLAIN服務器角色
ZMQ_PLAIN_USERNAME:設置PLAIN安全用戶名
ZMQ_PROBE_ROUTER:引導到ROUTER套接字的連接
ZMQ_RATE:設置組播數據速率
ZMQ_RCVBUF:設置內核接收緩沖區大小
ZMQ_RCVHWM:設置入站消息的高水位標記
ZMQ_RCVTIMEO:接收操作返回EAGAIN之前的最長時間
ZMQ_RECONNECT_IVL:設置重新連接間隔
ZMQ_RECONNECT_IVL_MAX:設置最大重連間隔
ZMQ_RECOVERY_IVL:設置組播恢復間隔
ZMQ_REQ_CORRELATE:將回復與請求進行匹配
ZMQ_REQ_RELAXED:放松請求和回復之間的嚴格交替
ZMQ_ROUTER_HANDOVER:在ROUTER套接字上處理重復的客戶身份
ZMQ_ROUTER_MANDATORY:只接受ROUTER套接字上可路由的消息
ZMQ_ROUTER_RAW:將ROUTER套接字切換到原始模式
ZMQ_SNDBUF:設置內核發送緩沖區大小
ZMQ_SNDHWM:設置出站消息的高水位標記
ZMQ_SNDTIMEO:發送操作返回EAGAIN之前的最長時間
ZMQ_SUBSCRIBE:建立消息過濾器
ZMQ_TCP_KEEPALIVE:重寫SO_KEEPALIVE套接字選項
ZMQ_TCP_KEEPALIVE_CNT:覆蓋TCP_KEEPCNT套接字選項
ZMQ_TCP_KEEPALIVE_IDLE:覆蓋TCP_KEEPCNT(或某些操作系統上的TCP_KEEPALIVE)
ZMQ_TCP_KEEPALIVE_INTVL:覆蓋TCP_KEEPINTVL套接字選項
ZMQ_TOS:在套接字上設置服務類型
ZMQ_UNSUBSCRIBE:刪除消息過濾器
ZMQ_XPUB_VERBOSE:提供XPUB套接字上的所有訂閱消息
ZMQ_ZAP_DOMAIN:設置RFC 27認證域
ZMQ_TCP_ACCEPT_FILTER:分配過濾器以允許新的TCP連接
ZMQ_IPC_FILTER_GID:分配組ID過濾器以允許新的IPC連接
ZMQ_IPC_FILTER_PID:分配進程ID過濾器以允許新的IPC連接
ZMQ_IPC_FILTER_UID:分配用戶ID過濾器以允許新的IPC連接
ZMQ_IPV4ONLY:在套接字上使用僅限IPv4
3.2.4 返回值
如果成功,zmq_setsockopt()函數將返回零。 否則它將返回-1並將errno設置為下面定義的值之一。
3.2.5 錯誤
EINVAL:請求的選項option_name未知,或請求的option_len或option_value無效。
ETERM:與指定套接字關聯的ZMQ上下文已終止。
ENOTSOCK:提供的套接字無效。
EINTR:信號傳遞中斷了操作。
4、建立消息流
4.1 zmq_bind(3)
4.1.1 名稱
zmq_bind - 接受套接字上的傳入連接
4.1.2 概要
int zmq_bind(void * socket,const char * endpoint);
4.1.3 描述
zmq_bind()函數將套接字綁定到本地端點,然後接受該端點上的傳入連接。
端點是一個由transport://後跟一個地址組成的字符串。 transport指定要使用的基礎協議。 地址指定要綁定的傳輸特定地址。
ZMQ提供以下傳輸:
TCP:使用TCP的單播傳輸,請參閱zmq_tcp(7)
IPC:本地進程間通信傳輸,請參見zmq_ipc(7)
INPROC:本地進程內(線程間)通信傳輸,請參見zmq_inproc(7)
pgm,epgm:使用PGM的可靠組播傳輸,請參見zmq_pgm(7)
每個ZMQ套接字類型(ZMQ_PAIR除外)都支持一對多和多對一的語義。 精確的語義取決於套接字類型,並在zmq_socket(3)中定義。
ipc和tcp傳輸接受通配符地址:有關詳細信息,請參閱zmq_ipc(7)和zmq_tcp(7)。
註:地址語法對於zmq_bind()和zmq_connect()尤其如此,特別是對於tcp,pgm和epgm傳輸。
在zmq_bind()之後,套接字進入靜音狀態,除非或者至少有一個輸入或輸出連接發生,此時套接字進入就緒狀態。 在靜音狀態下,套接字根據套接字類型阻塞或丟棄消息,如zmq_socket(3)中所定義。 相比之下,在libzmq:zmq_connect [3]之後,套接字進入就緒狀態。
4.1.4 返回值
如果成功,則zmq_bind()函數返回零。 否則它返回-1並將errno設置為下面定義的值之一。
4.1.5 錯誤
EINVAL:提供的端點無效。
EPROTONOSUPPORT:所請求的傳輸協議不受支持。
ENOCOMPATPROTO:請求的傳輸協議與套接字類型不兼容。
EADDRINUSE:請求的地址已被使用。
EADDRNOTAVAIL:請求的地址不在本地。
ENODEV:請求的地址指定一個不存在的接口。
ETERM:與指定套接字關聯的ZMQ上下文已終止。
ENOTSOCK:提供的套接字無效。
EMTHREAD:沒有I / O線程可用於完成任務。
4.2 zmq_connect(3)
4.2.1 名稱
zmq_connect - 從套接字創建傳出連接
4.2.2 概要
int zmq_connect(void * socket,const char * endpoint);
4.2.3 描述
zmq_connect()函數將套接字連接到端點,然後接受該端點上的傳入連接。
端點是一個由transport://後跟一個地址組成的字符串。 transport指定要使用的基礎協議。 該地址指定要連接的傳輸特定地址。
ZMQ提供以下傳輸:
TCP:使用TCP的單播傳輸,請參閱zmq_tcp(7)
IPC:本地進程間通信傳輸,請參見zmq_ipc(7)
INPROC:本地進程內(線程間)通信傳輸,請參見zmq_inproc(7)
pgm,epgm:使用PGM的可靠組播傳輸,請參見zmq_pgm(7)
每個ZMQ套接字類型(ZMQ_PAIR除外)都支持一對多和多對一的語義。 精確的語義取決於套接字類型,並在zmq_socket(3)中定義。
註:對於大多數傳輸和套接字類型,連接不會立即執行,而是由ZMQ根據需要執行。 因此,對zmq_connect()的成功調用並不意味著連接已經或可能實際建立。 因此,對於大多數傳輸和套接字類型,綁定服務器套接字並將套接字連接到客戶端的順序並不重要。 第一個例外是使用inproc:// transport時:您必須在調用zmq_connect()之前調用zmq_bind()。 第二個例外是ZMQ_PAIR套接字,它不會自動重新連接到端點。
在zmq_connect()之後,對於除ZMQ_ROUTER之外的套接字類型,套接字將進入其正常就緒狀態。 相比之下,僅在zmq_bind()之後,套接字將進入靜音狀態,其中套接字根據套接字類型阻塞或丟棄消息,如zmq_socket(3)中所定義。 ZMQ_ROUTER套接字只有在該對等體的握手完成時才會進入其正常就緒狀態,這可能需要任意時間。
4.2.4 返回值
如果成功,zmq_connect()函數返回零。 否則它返回-1並將errno設置為下面定義的值之一。
4.2.5 錯誤
EINVAL:提供的端點無效。
EPROTONOSUPPORT:所請求的傳輸協議不受支持。
ENOCOMPATPROTO:請求的傳輸協議與套接字類型不兼容。
ETERM:與指定套接字關聯的ZMQ上下文已終止。
ENOTSOCK:提供的套接字無效。
EMTHREAD:沒有I / O線程可用於完成任務。
4.3 zmq_disconnect()
4.3.1 名稱
zmq_disconnect - 斷開套接字
4.3.2 概要
int zmq_disconnect(void * socket,const char * endpoint);
4.3.3 描述
zmq_disconnect()函數應該將socket參數指定的套接字與endpoint參數指定的端點斷開連接。 從網絡物理接收但尚未通過zmq_recv()應用程序接收到的任何未完成消息都將被丟棄。 丟棄應用程序使用zmq_send()發送但尚未物理傳輸到網絡的消息的行為取決於指定套接字的ZMQ_LINGER套接字選項的值。
端點參數如zmq_connect(3)中所述。
註:ZMQ_LINGER的默認設置不會丟棄未發送的消息; 此行為可能會導致應用程序在調用zmq_term()時被阻止。 有關詳細信息,請參閱zmq_setsockopt(3)和zmq_term(3)。
4.3.4 返回值
如果成功,zmq_disconnect()函數將返回零。 否則它將返回-1並將errno設置為下面定義的值之一。
4.3.5 錯誤
EINVAL:提供的端點無效。
ETERM:與指定套接字關聯的ZMQ上下文已終止。
ENOTSOCK:提供的套接字無效。
ENOENT:提供的端點未連接。
4.4 zmq_unbind()
4.4.1 名稱
zmq_unbind - 停止接受套接字上的連接
4.4.2 概要
int zmq_unbind(void * socket,const char * endpoint);
4.4.3 描述
zmq_unbind()函數將從端點參數指定的端點解除由套接字參數指定的套接字。
端點參數如zmq_bind(3)中所述
從套接字解除通配符地址
當在zmq_bind()中使用通配符*端點(在zmq_tcp(7)和zmq_ipc(7)中描述)時,調用方應使用從ZMQ_LAST_ENDPOINT套接字選項中獲得的實際終點來從套接字解除綁定此端點。
4.4.4 返回值
如果成功,zmq_unbind()函數將返回零。 否則它將返回-1並將errno設置為下面定義的值之一。
4.4.5 錯誤
EINVAL:提供的端點無效。
ETERM:與指定套接字關聯的ZMQ上下文已終止。
ENOTSOCK:提供的套接字無效。
5、IO模型
5.1 zmq_poll
5.1.1 名稱
zmq_poll - 輸入/輸出復用
5.1.2 概要
int zmq_poll(zmq_pollitem_t * items,int nitems,long timeout);
5.1.3 描述
zmq_poll()函數為應用程序提供了一種機制,用於通過一組套接字以電平觸發方式復用輸入/輸出事件。 由items參數指向的數組的每個成員都是zmq_pollitem_t結構。 nitems參數指定items數組中的項目數。 zmq_pollitem_t結構定義如下:
typedef struct { void //*socket//; int //fd//; short //events//; short //revents//; } zmq_pollitem_t;
對於每個zmq_pollitem_t項目,對於事件中指定的事件,zmq_poll()應檢查由套接字引用的ZMQ套接字或由文件描述符fd指定的標準套接字。如果socket和fd都設置在一個zmq_pollitem_t中,則由套接字引用的ZMQ套接字應該優先,並且fd的值應該被忽略。
對於每個zmq_pollitem_t項目,zmq_poll()應首先清除revents成員,然後通過在revents成員中設置與事件條件相對應的位來指示發生的任何請求事件。
如果在任何zmq_pollitem_t項目上沒有發生所請求的事件,則zmq_poll()應等待超時毫秒,以便在任何請求的項目上發生事件。如果超時值為0,則應立即返回zmq_poll()。如果超時值為-1,則至少在一個zmq_pollitem_t上發生請求的事件之前,zmq_poll()應無限期地阻塞。
zmq_pollitem_t的事件和revents成員是通過OR組合以下事件標誌構造的位掩碼:
ZMQ_POLLIN:對於ZMQ套接字,至少可以從套接字接收一條消息而不會阻塞。 對於標準套接字,這相當於poll()系統調用的POLLIN標誌,通常意味著至少有一個字節的數據可以在不阻塞的情況下從fd中讀取。
ZMQ_POLLOUT:對於ZMQ套接字,至少有一條消息可能會發送到套接字而沒有阻塞。 對於標準套接字,這相當於poll()系統調用的POLLOUT標誌,通常意味著至少有一個字節的數據可以寫入fd而沒有阻塞。
ZMQ_POLLERR:對於標準套接字,此標誌通過zmq_poll()傳遞給底層的poll()系統調用,通常意味著由fd指定的套接字上存在某種錯誤條件。 對於ZMQ套接字,如果在事件中設置此標誌,則該標誌不起作用,並且絕不會由zmq_poll()返回。
註:zmq_poll()函數可以使用除poll()以外的操作系統接口來實現或模擬,因此可能會受到本文檔中未定義的那些接口的限制。
5.1.4 返回值
成功完成後,zmq_poll()函數應返回zmq_pollitem_t結構的數量,事件以revents標記,如果沒有事件發出信號,則返回0。 失敗時,zmq_poll()應返回-1並將errno設置為下面定義的值之一。
5.1.5 錯誤
ETERM:items數組中至少有一個成員是指其關聯的ZMQ上下文已終止的套接字。
EFAULT:提供的項目無效(NULL)。
EINTR:在任何事件發生之前,操作都會通過傳遞信號而中斷。
6、監視套接字事件
6.1 zmq_socket_monitor(3)
6.1.1 名稱
zmq_socket_monitor - 監視套接字事件
6.1.2 概要
int zmq_socket_monitor(void * socket,char * endpoint,int events);
6.1.3 描述
zmq_socket_monitor()方法允許應用程序線程跟蹤ZeroMQ套接字上的套接字事件(如連接)。 每次調用此方法都會創建一個ZMQ_PAIR套接字並將其綁定到指定的inproc://端點。 要收集套接字事件,您必須創建您自己的ZMQ_PAIR套接字,並將其連接到端點。
events參數是您希望監視的套接字事件的掩碼,請參閱下面的支持的事件。 要監視所有事件,請使用事件值ZMQ_EVENT_ALL。
每個事件都以兩個幀發送。 第一幀包含一個事件編號(16位)和一個根據事件編號提供附加數據的事件值(32位)。 第二幀包含一個字符串,用於指定受影響的TCP或IPC端點。
註:_zmq_socket_monitor()_方法僅支持面向連接運輸,即TCP,IPC和TIPC。
6.1.4 支持的事件
ZMQ_EVENT_CONNECTED:套接字已成功連接到遠程對等體。事件值是底層網絡套接字的文件描述符(FD)。警告:在您的代碼收到此事件時,不能保證FD仍然有效。
ZMQ_EVENT_CONNECT_DELAYED:套接字上的連接請求正在等待處理。事件值是未指定的。
ZMQ_EVENT_CONNECT_RETRIED:連接請求失敗,現在正在重試。事件值是以毫秒為單位的重新連接間隔。請註意,每次重試時重新計算重新連接間隔。
ZMQ_EVENT_LISTENING:套接字已成功綁定到網絡接口。事件值是底層網絡套接字的FD。警告:在您的代碼收到此事件時,不能保證FD仍然有效。
ZMQ_EVENT_BIND_FAILED:套接字無法綁定到給定的接口。事件值是由系統綁定調用生成的errno。
ZMQ_EVENT_ACCEPTED:套接字已經接受來自遠程對等體的連接。事件值是底層網絡套接字的FD。警告:在您的代碼收到此事件時,不能保證FD仍然有效。
ZMQ_EVENT_ACCEPT_FAILED:套接字已拒絕來自遠程對等方的連接。事件值是accept調用生成的errno。
ZMQ_EVENT_CLOSED:該插座已關閉。事件值是(現在已關閉)網絡套接字的FD。
ZMQ_EVENT_CLOSE_FAILED:套接字關閉失敗。事件值是系統調用返回的errno。請註意,此事件僅在IPC傳輸中發生。
ZMQ_EVENT_DISCONNECTED:插座意外斷開。事件值是底層網絡套接字的FD。警告:此插座將被關閉。
ZMQ_EVENT_MONITOR_STOPPED:此套接字上的監視已結束。
6.1.4 返回值
如果成功,zmq_socket_monitor()函數返回0或更大的值。 否則它返回-1並將errno設置為下面定義的值之一。
6.1.5 錯誤
ETERM:與指定套接字關聯的ZMQ上下文已終止。
EPROTONOSUPPORT:所請求的傳輸協議不受支持。 Monitor套接字需要使用inproc://傳輸。
EINVAL:提供的端點無效。
ZeroMQ API(四) 套接字