/src/wrappers/zmq/library/zmq_context.e

  1class ZMQ_CONTEXT
  2	-- An ØMQ Context where ØMQ sockets live within.
  3	
  4	-- Each ØMQ socket  lives  within  a  specific  context.  Creating  and
  5	-- destroying context is a counterpart of library
  6	-- initialisation/deinitialisation as used elsewhere. Ability to create
  7	-- multiple  contexts saves  the  day  when an application happens to
  8	-- link (indirectly and involuntarily) with several instances of 0MQ.
  9
 10	-- Implementation notes: the fact that ØMQ can work in a threaded
 11	-- enviroment is currently hidden by this Liberty wrappers
 12
 13	-- TODO: add support for pollability (ZMQ_POLL)
 14
 15inherit 
 16	WRAPPER redefine default_create end
 17	EIFFEL_OWNED redefine default_create, dispose end 
 18
 19insert 
 20	ZMQ_EXTERNALS undefine default_create end
 21	ZMQ_SOCKET_TYPES undefine default_create end
 22
 23create {ANY} default_create
 24feature {} -- Creation
 25	default_create
 26		-- Context creation; currently only non-threaded programs are handled.
 27	do
 28		from_external_pointer(zmq_init(1))
 29	end
 30feature {} -- Disposing
 31	dispose
 32		local res: INTEGER
 33		do
 34			res := zmq_term(handle)
 35			-- TODO: handle return value
 36		end
 37feature {ANY} -- Comparison and copying
 38
 39	-- Since a ZMQ_CONTEXT is entirely opaque object they are not
 40	-- distinguishable so is_equal is always True. Copying just create another
 41	-- context.
 42
 43	is_equal (another: like Current): BOOLEAN
 44		do
 45			Result:=True
 46		end
 47
 48	copy (another: like Current)
 49		do
 50			default_create	
 51		end
 52
 53feature {ANY} -- Request-reply pattern
 54
 55	-- The request-reply pattern is used for sending requests from a client to
 56	-- one or more instances of a service, and receiving subsequent replies to
 57	-- each request sent.
 58
 59	new_req_socket: ZMQ_REQ_SOCKET
 60		-- A new ZMQ_REQ_SOCKET, that sends requests to and receives replies from a service.
 61		-- This socket type allows only an alternating sequence of request -
 62		-- sending a message - and subsequent reply - receiving an answer. Each
 63		-- request sent is load-balanced among all services, and each reply
 64		-- received is matched with the last issued request.
 65	do
 66		create Result.from_external_pointer (zmq_socket(handle,zmq_req))
 67	ensure Result/=Void
 68	end
 69
 70	new_rep_socket: ZMQ_REP_SOCKET
 71		-- A new ZMQ_REP socket to receive requests from and send replies to a client. 
 72
 73		-- It allows only an alternating sequence of request (receive) and 
 74		-- subsequent reply (send) commands. Each request received
 75		-- fair-queued from among all clients, and each reply sent is routed to
 76		-- the client that issued the last request. If the original requester
 77		-- doesn’t exist any more the reply is silently discarded.
 78		
 79			do
 80		create Result.from_external_pointer(zmq_socket(handle,zmq_rep))
 81	ensure Result/=Void
 82	end
 83
 84--        ZMQ_DEALER
 85-- 	   A socket of type ZMQ_DEALER is an advanced pattern used for extending request/reply
 86-- 	   sockets. Each message sent is load-balanced among all connected peers, and each
 87-- 	   message received is fair-queued from all connected peers.
 88-- 
 89-- 	   Previously this socket was called ZMQ_XREQ and that name remains available for
 90-- 	   backwards compatibility.
 91-- 
 92-- 	   When a ZMQ_DEALER socket enters an exceptional state due to having reached the high
 93-- 	   water mark for all peers, or if there are no peers at all, then any zmq_send(3)
 94-- 	   operations on the socket shall block until the exceptional state ends or at least one
 95-- 	   peer becomes available for sending; messages are not discarded.
 96-- 
 97-- 	   When a ZMQ_DEALER socket is connected to a ZMQ_REP socket each message sent must
 98-- 	   consist of an empty message part, the delimiter, followed by one or more body parts.
 99-- 
100-- 	   Table 3. Summary of ZMQ_DEALER characteristics
101-- 	   Compatible peer sockets     ZMQ_ROUTER, ZMQ_REQ, ZMQ_REP
102-- 
103-- 	   Direction		       Bidirectional
104-- 
105-- 	   Send/receive pattern        Unrestricted
106-- 
107-- 	   Outgoing routing strategy   Load-balanced
108-- 
109-- 	   Incoming routing strategy   Fair-queued
110-- 
111-- 
112-- 
113-- 	   ZMQ_HWM option action       Block
114-- 
115-- 
116--        ZMQ_ROUTER
117	-- 	   A socket of type ZMQ_ROUTER is an advanced pattern used for extending request/reply
118-- 	   sockets. When receiving messages a ZMQ_ROUTER socket shall prepend a message part
119-- 	   containing the identity of the originating peer to the message before passing it to
120-- 	   the application. Messages received are fair-queued from among all connected peers.
121-- 	   When sending messages a ZMQ_ROUTER socket shall remove the first part of the message
122-- 	   and use it to determine the identity of the peer the message shall be routed to. If
123-- 	   the peer does not exist anymore the message shall be silently discarded.
124-- 
125-- 	   Previously this socket was called ZMQ_XREP and that name remains available for
126-- 	   backwards compatibility.
127-- 
128-- 	   When a ZMQ_ROUTER socket enters an exceptional state due to having reached the high
129-- 	   water mark for all peers, or if there are no peers at all, then any messages sent to
130-- 	   the socket shall be dropped until the exceptional state ends. Likewise, any messages
131-- 	   routed to a non-existent peer or a peer for which the individual high water mark has
132-- 	   been reached shall also be dropped.
133-- 
134-- 	   When a ZMQ_REQ socket is connected to a ZMQ_ROUTER socket, in addition to the identity
135-- 	   of the originating peer each message received shall contain an empty delimiter message
136-- 	   part. Hence, the entire structure of each received message as seen by the application
137-- 	   becomes: one or more identity parts, delimiter part, one or more body parts. When
138-- 	   sending replies to a ZMQ_REQ socket the application must include the delimiter part.
139-- 
140-- 	   Table 4. Summary of ZMQ_ROUTER characteristics
141-- 	   Compatible peer sockets     ZMQ_DEALER, ZMQ_REQ, ZMQ_REP
142-- 
143-- 	   Direction		       Bidirectional
144-- 
145-- 	   Send/receive pattern        Unrestricted
146-- 
147-- 	   Outgoing routing strategy   See text
148-- 
149-- 	   Incoming routing strategy   Fair-queued
150-- 
151-- 	   ZMQ_HWM option action       Drop
152-- 
153-- 
154feature {ANY} -- Publish-subscribe pattern
155
156	-- The publish-subscribe pattern is used for one-to-many distribution of
157	-- data from a single publisher to multiple subscribers in a fan out
158	-- fashion.
159
160	new_pub_socket: ZMQ_PUB_SOCKET
161		-- A new ZMQ_PUB_SOCKET, used by a publisher to distribute data.
162		-- Messages sent are distributed in a fan out fashion to all connected
163		-- peers. 
164
165		-- When a ZMQ_PUB_SOCKET enters an exceptional state due to having
166		-- reached the high water mark for a subscriber, then any messages that
167		-- would be sent to the subscriber in question shall instead be dropped
168		-- until the exceptional state ends. The `send' command shall never
169		-- block for this socket type.
170	do
171		create Result.from_external_pointer(zmq_socket(handle,zmq_pub))
172	ensure Result/=Void
173	end
174
175
176	new_sub_socket: ZMQ_SUB_SOCKET
177		-- A new ZMQ_SUB_SOCKET used by a subscriber to subscribe to data
178		-- distributed by a publisher.  Initially this socket is not subscribed
179		-- to any messages, use `subscribe_to' or `subscribe_to_all' to specify
180		-- which messages to subscribe to. This is a receiving only socket.
181	do
182		create Result.from_external_pointer(zmq_socket(handle,zmq_sub))
183	ensure Result/=Void
184	end
185
186
187feature {ANY} --    Pipeline pattern
188	
189	-- The pipeline pattern is used for distributing data to nodes arranged in
190	-- a pipeline. Data always flows down the pipeline, and each stage of the
191	-- pipeline is connected to at least one node. When a pipeline stage
192	-- connected to multiple nodes data is load-balanced among all connected
193	-- nodes.
194
195	new_push_socket: ZMQ_PUSH_SOCKET
196		-- A new socket used in a pipeline node to send messages to downstream
197		-- pipeline nodes. Messages are load-balanced to all connected
198		-- downstream nodes. 
199		
200		-- When a ZMQ_PUSH_SOCKET enters an exceptional state due to having
201		-- reached the high water mark for all downstream nodes, or if there
202		-- are no downstream nodes at all, then any send operations on the
203		-- socket shall block until the exceptional state ends or at least one
204		-- downstream node becomes available for sending; messages are not
205		-- discarded.
206		 
207		--   Summary of ZMQ_PUSH characteristics
208		--   Compatible peer sockets     ZMQ_PULL
209		--
210		--   Direction		       Unidirectional
211		--
212		--   Send/receive pattern        Send only
213		--
214		--   Incoming routing strategy   N/A
215		--
216		--   Outgoing routing strategy   Load-balanced
217		--
218		--   ZMQ_HWM option action       Block
219	do
220		create Result.from_external_pointer(zmq_socket(handle,zmq_push))
221	ensure Result/=Void
222	end
223
224	new_pull_socket: ZMQ_PULL_SOCKET
225		--
226		--        ZMQ_PULL
227		-- 	   A socket of type ZMQ_PULL is used by a pipeline node to receive messages from upstream
228		-- 	   pipeline nodes. Messages are fair-queued from among all connected upstream nodes. The
229		-- 	   zmq_send() function is not implemented for this socket type.
230		-- 
231		-- 	   Deprecated alias: ZMQ_UPSTREAM.
232		-- 
233		-- 	   Table 8. Summary of ZMQ_PULL characteristics
234		-- 	   Compatible peer sockets     ZMQ_PUSH
235		-- 
236		-- 	   Direction		       Unidirectional
237		-- 
238		-- 	   Send/receive pattern        Receive only
239		-- 
240		-- 	   Incoming routing strategy   Fair-queued
241		-- 
242		-- 	   Outgoing routing strategy   N/A
243		-- 
244		-- 	   ZMQ_HWM option action       N/A
245		-- 
246		-- 
247	do
248		create Result.from_external_pointer(zmq_socket(handle,zmq_pull))
249	ensure Result/=Void
250	end
251
252
253feature {ANY} -- Exclusive pair pattern
254
255--        The exclusive pair pattern is used to connect a peer to precisely one other peer. This
256--        pattern is used for inter-thread communication across the inproc transport.
257-- 
258--        ZMQ_PAIR
259-- 	   A socket of type ZMQ_PAIR can only be connected to a single peer at any one time. No
260-- 	   message routing or filtering is performed on messages sent over a ZMQ_PAIR socket.
261-- 
262-- 	   When a ZMQ_PAIR socket enters an exceptional state due to having reached the high
263-- 	   water mark for the connected peer, or if no peer is connected, then any zmq_send(3)
264-- 	   operations on the socket shall block until the peer becomes available for sending;
265-- 	   messages are not discarded.
266-- 
267-- 	       Note
268-- 	       ZMQ_PAIR sockets are designed for inter-thread communication across the
269-- 	       zmq_inproc(7) transport and do not implement functionality such as
270-- 	       auto-reconnection. ZMQ_PAIR sockets are considered experimental and may have other
271-- 	       missing or broken aspects.
272-- 
273-- 	   Table 9. Summary of ZMQ_PAIR characteristics
274-- 	   Compatible peer sockets     ZMQ_PAIR
275-- 
276-- 	   Direction		       Bidirectional
277-- 
278-- 	   Send/receive pattern        Unrestricted
279-- 
280-- 	   Incoming routing strategy   N/A
281-- 
282-- 	   Outgoing routing strategy   N/A
283-- 
284-- 	   ZMQ_HWM option action       Block
285
286
287end -- class ZMQ_CONTEXT
288
289-- Zero MQ Liberty Wrappers
290
291-- Copyright (C) 2010-2017: Paolo Redaelli 
292
293-- This library is free software; you can redistribute it and/or
294-- modify it under the terms of the GNU Lesser General Public
295-- License as published by the Free Software Foundation; either
296-- version 3 of the License, or (at your option) any later version.
297-- 
298-- This library is distributed in the hope that it will be useful,
299-- but WITHOUT ANY WARRANTY; without even the implied warranty of
300-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
301-- Lesser General Public License for more details.
302-- 
303-- You should have received a copy of the GNU Lesser General Public
304-- License along with this library; if not, write to the Free Software
305-- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
306