core.socket

Module: core.socket

0MQ Socket class.

Socket

class zmq.core.socket.Socket(context, socket_type)

A 0MQ socket.

These objects will generally be constructed via the socket() method of a Context object.

Note: 0MQ Sockets are not threadsafe. DO NOT share them across threads.

Parameters :

context : Context

The 0MQ Context this Socket belongs to.

socket_type : int

The socket type, which can be any of the 0MQ socket types: REQ, REP, PUB, SUB, PAIR, XREQ, DEALER, XREP, ROUTER, PULL, PUSH, XPUB, XSUB.

See also

Context.socket

method for creating a socket bound to a Context.

bind(addr)

Bind the socket to an address.

This causes the socket to listen on a network port. Sockets on the other side of this connection will use Socket.connect(addr) to connect to this socket.

Parameters :

addr : str

The address string. This has the form ‘protocol://interface:port’, for example ‘tcp://127.0.0.1:5555’. Protocols supported include tcp, udp, pgm, epgm, inproc and ipc. If the address is unicode, it is encoded to utf-8 first.

bind_to_random_port(addr, min_port=49152, max_port=65536, max_tries=100)

Bind this socket to a random port in a range.

Parameters :

addr : str

The address string without the port to pass to Socket.bind().

min_port : int, optional

The minimum port in the range of ports to try (inclusive).

max_port : int, optional

The maximum port in the range of ports to try (exclusive).

max_tries : int, optional

The maximum number of bind attempts to make.

Returns :

port : int

The port the socket was bound to.

Raises :

ZMQBindError :

if max_tries reached before successful bind

close(linger=None)

Close the socket.

If linger is specified, LINGER sockopt will be set prior to closing.

This can be called to close the socket by hand. If this is not called, the socket will automatically be closed when it is garbage collected.

closed

connect(addr)

Connect to a remote 0MQ socket.

Parameters :

addr : str

The address string. This has the form ‘protocol://interface:port’, for example ‘tcp://127.0.0.1:5555’. Protocols supported are tcp, upd, pgm, inproc and ipc. If the address is unicode, it is encoded to utf-8 first.

context

getsockopt(option)

Get the value of a socket option.

See the 0MQ API documentation for details on specific options.

Parameters :

option : int

The option to get. Available values will depend on your version of libzmq. Examples include:

zmq.IDENTITY, HWM, LINGER, FD, EVENTS

Returns :

optval : int or bytes

The value of the option as a bytestring or int.

getsockopt_string(option, encoding='utf-8')

Get the value of a socket option.

See the 0MQ documentation for details on specific options.

Parameters :

option : int

The option to retrieve. Currently, IDENTITY is the only gettable option that can return a string.

Returns :

optval : unicode string (unicode on py2, str on py3)

The value of the option as a unicode string.

getsockopt_unicode(option, encoding='utf-8')

Get the value of a socket option.

See the 0MQ documentation for details on specific options.

Parameters :

option : int

The option to retrieve. Currently, IDENTITY is the only gettable option that can return a string.

Returns :

optval : unicode string (unicode on py2, str on py3)

The value of the option as a unicode string.

poll(timeout=None, flags=POLLIN)

Poll the socket for events. The default is to poll forever for incoming events. Timeout is in milliseconds, if specified.

Parameters :

timeout : int [default: None]

The timeout (in milliseconds) to wait for an event. If unspecified (or secified None), will wait forever for an event.

flags : bitfield (int) [default: POLLIN]

The event flags to poll for (any combination of POLLIN|POLLOUT). The default is to check for incoming events (POLLIN).

Returns :

events : bitfield (int)

The events that are ready and waiting. Will be 0 if no events were ready by the time timeout was reached.

recv(flags=0, copy=True, track=False)

Receive a message.

Parameters :

flags : int

Any supported flag: NOBLOCK. If NOBLOCK is set, this method will raise a ZMQError with EAGAIN if a message is not ready. If NOBLOCK is not set, then this method will block until a message arrives.

copy : bool

Should the message be received in a copying or non-copying manner? If False a Frame object is returned, if True a string copy of message is returned.

track : bool

Should the message be tracked for notification that ZMQ has finished with it? (ignored if copy=True)

Returns :

msg : bytes, Frame

The received message frame. If copy is False, then it will be a Frame, otherwise it will be bytes.

Raises :

ZMQError :

for any of the reasons zmq_recvmsg might fail.

recv_json(flags=0)

Receive a Python object as a message using json to serialize.

Parameters :

flags : int

Any valid recv flag.

Returns :

obj : Python object

The Python object that arrives as a message.

recv_multipart(flags=0, copy=True, track=False)

Receive a multipart message as a list of bytes or Frame objects.

Parameters :

flags : int, optional

Any supported flag: NOBLOCK. If NOBLOCK is set, this method will raise a ZMQError with EAGAIN if a message is not ready. If NOBLOCK is not set, then this method will block until a message arrives.

copy : bool, optional

Should the message frame(s) be received in a copying or non-copying manner? If False a Frame object is returned for each part, if True a copy of the bytes is made for each frame.

track : bool, optional

Should the message frame(s) be tracked for notification that ZMQ has finished with it? (ignored if copy=True)

Returns :

——- :

msg_parts : list

A list of frames in the multipart message; either Frames or bytes, depending on copy.

recv_pyobj(flags=0)

Receive a Python object as a message using pickle to serialize.

Parameters :

flags : int

Any valid recv flag.

Returns :

obj : Python object

The Python object that arrives as a message.

recv_string(flags=0, encoding='utf-8')

Receive a unicode string, as sent by send_string.

Parameters :

flags : int

Any valid recv flag.

encoding : str [default: ‘utf-8’]

The encoding to be used

Returns :

s : unicode string (unicode on py2, str on py3)

The Python unicode string that arrives as encoded bytes.

recv_unicode(flags=0, encoding='utf-8')

Receive a unicode string, as sent by send_string.

Parameters :

flags : int

Any valid recv flag.

encoding : str [default: ‘utf-8’]

The encoding to be used

Returns :

s : unicode string (unicode on py2, str on py3)

The Python unicode string that arrives as encoded bytes.

send(data, flags=0, copy=True, track=False)

Send a message on this socket.

This queues the message to be sent by the IO thread at a later time.

Parameters :

data : object, str, Frame

The content of the message.

flags : int

Any supported flag: NOBLOCK, SNDMORE.

copy : bool

Should the message be sent in a copying or non-copying manner.

track : bool

Should the message be tracked for notification that ZMQ has finished with it? (ignored if copy=True)

Returns :

None : if copy or not track

None if message was sent, raises an exception otherwise.

MessageTracker : if track and not copy

a MessageTracker object, whose pending property will be True until the send is completed.

Raises :

TypeError :

If a unicode object is passed

ValueError :

If track=True, but an untracked Frame is passed.

ZMQError :

If the send does not succeed for any reason.

send_json(obj, flags=0)

Send a Python object as a message using json to serialize.

Parameters :

obj : Python object

The Python object to send.

flags : int

Any valid send flag.

send_multipart(msg_parts, flags=0, copy=True, track=False)

Send a sequence of buffers as a multipart message.

Parameters :

msg_parts : iterable

A sequence of objects to send as a multipart message. Each element can be any sendable object (Frame, bytes, buffer-providers)

flags : int, optional

SNDMORE is handled automatically for frames before the last.

copy : bool, optional

Should the frame(s) be sent in a copying or non-copying manner.

track : bool, optional

Should the frame(s) be tracked for notification that ZMQ has finished with it (ignored if copy=True).

Returns :

None : if copy or not track

MessageTracker : if track and not copy

a MessageTracker object, whose pending property will be True until the last send is completed.

send_pyobj(obj, flags=0, protocol=-1)

Send a Python object as a message using pickle to serialize.

Parameters :

obj : Python object

The Python object to send.

flags : int

Any valid send flag.

protocol : int

The pickle protocol number to use. Default of -1 will select the highest supported number. Use 0 for multiple platform support.

send_string(u, flags=0, copy=False, encoding='utf-8')

Send a Python unicode string as a message with an encoding.

0MQ communicates with raw bytes, so you must encode/decode text (unicode on py2, str on py3) around 0MQ.

Parameters :

u : Python unicode string (unicode on py2, str on py3)

The unicode string to send.

flags : int, optional

Any valid send flag.

encoding : str [default: ‘utf-8’]

The encoding to be used

send_unicode(u, flags=0, copy=False, encoding='utf-8')

Send a Python unicode string as a message with an encoding.

0MQ communicates with raw bytes, so you must encode/decode text (unicode on py2, str on py3) around 0MQ.

Parameters :

u : Python unicode string (unicode on py2, str on py3)

The unicode string to send.

flags : int, optional

Any valid send flag.

encoding : str [default: ‘utf-8’]

The encoding to be used

setsockopt(option, optval)

Set socket options.

See the 0MQ API documentation for details on specific options.

Parameters :

option : int

The option to set. Available values will depend on your version of libzmq. Examples include:

zmq.SUBSCRIBE, UNSUBSCRIBE, IDENTITY, HWM, LINGER, FD

optval : int or bytes

The value of the option to set.

setsockopt_string(option, optval, encoding='utf-8')

Set socket options with a unicode object it is simply a wrapper for setsockopt to protect from encoding ambiguity.

See the 0MQ documentation for details on specific options.

Parameters :

option : int

The name of the option to set. Can be any of: SUBSCRIBE, UNSUBSCRIBE, IDENTITY

optval : unicode string (unicode on py2, str on py3)

The value of the option to set.

encoding : str

The encoding to be used, default is utf8

setsockopt_unicode(option, optval, encoding='utf-8')

Set socket options with a unicode object it is simply a wrapper for setsockopt to protect from encoding ambiguity.

See the 0MQ documentation for details on specific options.

Parameters :

option : int

The name of the option to set. Can be any of: SUBSCRIBE, UNSUBSCRIBE, IDENTITY

optval : unicode string (unicode on py2, str on py3)

The value of the option to set.

encoding : str

The encoding to be used, default is utf8

socket_type