Skip to content

Migrating to v4

Jump to bottom
Drew Noakes edited this page Jun 29, 2016 · 2 revisions

Migration from NetMQ version 3 to 4

NetMQ version 4 introduces some breaking changes for code migrated from version 3. These changes simplify the use of NetMQ, and the migration is not so difficult.

Should I upgrade?

NetMQ version 3 will continue to receive bug fixes, but new features and improvements will be made to version 4 only. We expect most users will benefit from upgrading and encourage doing so.

How to upgrade?

  1. Make sure you take the latest release of the NetMQ 3 family from NuGet.
  2. Address any compiler warnings about usages of obsolete code. The compiler warnings will guide you regarding what changes are required.
  3. Uninstall the NetMQ NuGet package, and install the NetMQ4 package instead.

Changes

Much of the removed code have been marked [Obsolete] for several releases now, so many of the changes shown here are unlikely to apply to your code. Further, any one application is unlikely to depend upon much of the public API of NetMQ. Don't let the length of this list concern you.

For completeness, all API changes are detailed here.

The context

NetMQContext has been removed. Previously you'd create one of these in your application and pass it around. NetMQ now manages this internally, making the API simpler.

Here's a comparison:

// NetMQ version 3
using (var context = NetMQContext.Create())
using (var publisher = context.CreatePublisherSocket())
{
    // ...
}

// NetMQ version 4
using (var publisher = new PublisherSocket())
{
    // ...
}

Note the factory methods for sockets no longer exist. Instead, just call the constructor of the type you want to use.

  • NetMQContext.CreateRequestSocket() 👉 new RequestSocket()
  • NetMQContext.CreateResponseSocket() 👉 new ResponseSocket()
  • NetMQContext.CreateDealerSocket() 👉 new DealerSocket()
  • NetMQContext.CreateRouterSocket() 👉 new RouterSocket()
  • NetMQContext.CreateXPublisherSocket() 👉 new XPublisherSocket()
  • NetMQContext.CreatePairSocket() 👉 new PairSocket()
  • NetMQContext.CreatePushSocket() 👉 new PushSocket()
  • NetMQContext.CreatePublisherSocket() 👉 new PublisherSocket()
  • NetMQContext.CreatePullSocket() 👉 new PullSocket()
  • NetMQContext.CreateSubscriberSocket() 👉 new SubscriberSocket()
  • NetMQContext.CreateXSubscriberSocket() 👉 new XSubscriberSocket()
  • NetMQContext.CreateStreamSocket() 👉 new StreamSocket()
  • NetMQContext.CreateMonitorSocket() 👉 new MonitorSocket()

Further, constructors of the following classes no longer receive a context and calls should be updated:

  • NetMQForwarder
  • NetMQBeacon
  • QueueDevice
  • StreamerDevice
  • NetMQMonitor

These factory methods no longer accept context instances:

  • NetMQActor.Create

Poller and Scheduler

The Poller and NetMQScheduler classes have been merged into the new NetMQPoller class.

  • Poller 👉 NetMQPoller

Adding and removing objects to poll:

  • Poller.AddSocket 👉 NetMQPoller.Add
  • Poller.AddTimer 👉 NetMQPoller.Add
  • Poller.AddPollInSocket 👉 NetMQPoller.Add
  • Poller.RemoveSocket 👉 NetMQPoller.Remove
  • Poller.RemoveTimer 👉 NetMQPoller.Remove
  • Poller.RemovePollInSocket 👉 NetMQPoller.Remove

Starting and stopping the poller.

  • Poller.PollTillCancelled 👉 NetMQPoller.Run
  • Poller.PollTillCancelledNonBlocking 👉 NetMQPoller.RunAsync
  • Poller.Cancel 👉 NetMQPoller.Stop
  • Poller.CancelNonBlocking 👉 NetMQPoller.StopAsync

Scheduling for the TPL:

  • NetMQScheduler 👉 NetMQPoller

By changing the Add* names to all be the same as simply Add, and by implementing IEnumerable, NetMQPoller now supports collection initialiser syntax:

new NetMQPoller { publisher, subscriber, timer, tcpSocket }

NetMQPoller now implements ISynchronizeInvoke (and continues extending TaskScheduler), so it can be used to get schedule and synchronise work on the poller's thread from both the TPL and earlier BCL APIs.

Receiving

Receiving a single frame using Msg:

  • IReceivingSocket.Receive(ref Msg, SendReceiveOptions) 👉
    • Receive(ref Msg)
    • TryReceive(ref Msg, TimeSpan) : bool

Receiving a single frame as a byte[]:

  • IReceivingSocket.Receive() : byte[]
  • IReceivingSocket.Receive(out bool) : byte[]
  • IReceivingSocket.Receive(bool, out bool) : byte[]
  • IReceivingSocket.Receive(SendReceiveOptions) : byte[]
  • IReceivingSocket.Receive(SendReceiveOptions, out bool) : byte[]
  • IReceivingSocket.Receive(TimeSpan) : byte[] 👉
    • ReceiveFrameBytes(): byte[]
    • ReceiveFrameBytes(out bool): byte[]
    • TryReceiveFrameBytes(out byte[]) : bool
    • TryReceiveFrameBytes(out byte[], out bool) : bool
    • TryReceiveFrameBytes(TimeSpan, out byte[]) : bool
    • TryReceiveFrameBytes(TimeSpan, out byte[], out bool) : bool

Receiving an entire multipart message as List<byte[]>:

  • IReceivingSocket.ReceiveMessages() : List<byte[]>(int)
  • IReceivingSocket.ReceiveAll() : List<byte[]>(int) 👉
    • IReceivingSocket.ReceiveMultipartBytes(int) : List<byte[]>
    • IReceivingSocket.ReceiveMultipartBytes(ref List<byte[]>, int): void
    • IReceivingSocket.TryReceiveMultipartBytes(ref List<byte[]>, int): bool
    • IReceivingSocket.TryReceiveMultipartBytes(TimeSpan, ref List<byte[]>, int): bool

Receiving a single frame as a string:

  • IReceivingSocket.ReceiveString() : string
  • IReceivingSocket.ReceiveString(SendReceiveOptions) : string
  • IReceivingSocket.ReceiveString(SendReceiveOptions, out bool) : string
  • IReceivingSocket.ReceiveString(Encoding) : string
  • IReceivingSocket.ReceiveString(Encoding, SendReceiveOptions) : string
  • IReceivingSocket.ReceiveString(Encoding, SendReceiveOptions, out bool) : string
  • IReceivingSocket.ReceiveString(out bool) : string
  • IReceivingSocket.ReceiveString(bool, out bool) : string
  • IReceivingSocket.ReceiveString(TimeSpan) : string
  • IReceivingSocket.ReceiveString(Encoding, out bool) : string
  • IReceivingSocket.ReceiveString(Encoding, bool, out bool) : string
  • IReceivingSocket.ReceiveString(Encoding, TimeSpan) : string 👉
    • IReceivingSocket.ReceiveFrameString() : string
    • IReceivingSocket.ReceiveFrameString(out bool) : string
    • IReceivingSocket.ReceiveFrameString(Encoding) : string
    • IReceivingSocket.ReceiveFrameString(Encoding, out bool) : string
    • IReceivingSocket.TryReceiveFrameString(out string) : bool
    • IReceivingSocket.TryReceiveFrameString(out string, out bool) : bool
    • IReceivingSocket.TryReceiveFrameString(Encoding, out string) : bool
    • IReceivingSocket.TryReceiveFrameString(Encoding, out string, out bool) : bool
    • IReceivingSocket.TryReceiveFrameString(TimeSpan, out string) : bool
    • IReceivingSocket.TryReceiveFrameString(TimeSpan, out string, out bool) : bool
    • IReceivingSocket.TryReceiveFrameString(TimeSpan, Encoding, out string) : bool
    • IReceivingSocket.TryReceiveFrameString(TimeSpan, Encoding, out string, out bool) : bool

Receiving an entire multipart message as List<string>:

  • IReceivingSocket.ReceiveStringMessages(int) : List<string>
  • IReceivingSocket.ReceiveStringMessages(Encoding, int) : List<string>
  • IReceivingSocket.ReceiveAllString() : List<string> 👉
    • IReceivingSocket.ReceiveMultipartStrings() : List<string>
    • IReceivingSocket.ReceiveMultipartStrings(out bool) : List<string>
    • IReceivingSocket.TryReceiveMultipartStrings(ref List<string>, int) : bool
    • IReceivingSocket.TryReceiveMultipartStrings(Encoding, ref List<string>, int) : bool
    • IReceivingSocket.TryReceiveMultipartStrings(TimeSpan, ref List<string>, int) : bool
    • IReceivingSocket.TryReceiveMultipartStrings(TimeSpan, Encoding, ref List<string>, int) : bool

Receiving an entire multipart message as NetMQMessage:

  • IReceivingSocket.ReceiveMessage(bool) : NetMQMessage
  • IReceivingSocket.ReceiveMessage(NetMQMessage, bool) : void
  • IReceivingSocket.ReceiveMessage(TimeSpan) : NetMQMessage 👉
    • IReceivingSocket.ReceiveMultipartMessage(int) : NetMQMessage
    • IReceivingSocket.TryReceiveMultipartMessage(ref NetMQMessage, int): bool
    • IReceivingSocket.TryReceiveMultipartMessage(TimeSpan ref NetMQMessage, int): bool

Receiving a signal:

  • IReceivingSocket.WaitForSignal() : bool 👉
    • IReceivingSocket.ReceiveSignal(): bool
    • IReceivingSocket.TryReceiveSignal(out bool): bool
    • IReceivingSocket.TryReceiveSignal(TimeSpan, out bool): bool

The ability to skip a frame has been added:

  • IReceivingSocket.SkipFrame(): bool
  • IReceivingSocket.SkipFrame(out bool): bool
  • IReceivingSocket.TrySkipFrame(): bool
  • IReceivingSocket.TrySkipFrame(out bool): bool
  • IReceivingSocket.TrySkipFrame(TimeSpan): bool
  • IReceivingSocket.TrySkipFrame(TimeSpan, out bool): bool

As well as the ability to skip entire multipart messages, or the remainder of the current message when partially received:

  • IReceivingSocket.SkipMultipartMessage(): bool

  • IReceivingSocket.TrySkipMultipartMessage(): bool

  • IReceivingSocket.TrySkipMultipartMessage(TimeSpan): bool

  • NetMQSocketEventArgs.ReceiveReady 👉 NetMQSocketEventArgs.IsReadyToReceive

Sending

  • IOutgoingSocket.Send(ref Msg, SendReceiveOptions) 👉

    • Send(ref Msg, bool)
    • TrySend(ref Msg, TimeSpan, bool)

  • IOutgoingSocket.Send(byte[], int, SendReceiveOptions)

  • IOutgoingSocket.Send(byte[], int, bool, bool)

  • IOutgoingSocket.Send(byte[])

  • IOutgoingSocket.SendMore(byte[], bool)

  • IOutgoingSocket.SendMore(byte[], int, bool) 👉

    • SendFrame(byte[], bool)
    • SendFrame(byte[], int, bool)
    • SendMoreFrame(byte[])
    • SendMoreFrame(byte[], int)
    • TrySendFrame(TimeSpan, byte[], bool)
    • TrySendFrame(TimeSpan, byte[], int, bool)
    • TrySendFrame(byte[], bool)
    • TrySendFrame(byte[], int, bool)

  • IOutgoingSocket.Send(string, bool, bool)

  • IOutgoingSocket.Send(string, Encoding, SendReceiveOptions)

  • IOutgoingSocket.Send(string, Encoding, bool, bool)

  • IOutgoingSocket.SendMore(string, bool)

  • IOutgoingSocket.SendMore(string, Encoding, bool) 👉

    • SendFrame(string, bool)
    • SendMoreFrame(string)
    • TrySendFrame(TimeSpan, string, bool)
    • TrySendFrame(string, bool)

  • IOutgoingSocket.SendMessage(NetMQMessage, bool) 👉

    • SendMultipartMessage(NetMQMessage)
    • TrySendMultipartMessage(NetMQMessage)
    • TrySendMultipartMessage(TimeSpan, NetMQMessage)

  • NetMQSocketEventArgs.SendReady 👉 NetMQSocketEventArgs.IsReadyToSend

Subscribe / Unsubscribe

The Subscribe and Unsubscribe methods have been pushed down the class hierarchy from NetMQSocket to only those subclasses to which subscription applies (SubscriberSocket and XSubscriberSocket). This shouldn't affect any correct code, but is mentioned here for completeness.

Socket Options

Some unused socket options were removed:

  • ReceiveTimeout (use overloads of TryReceive that accept a TimeSpan)
  • SendTimeout (use overloads of TrySend that accept a TimeSpan)
  • TcpAcceptFilter
  • TcpKeepaliveCnt
  • CopyMessages
  • ReceivevBuffer 👉 ReceiveBuffer (typo)
  • GetLastEndpoint 👉 LastEndpoint

Exceptions

  • ErrorPollingException was unused and has been removed
  • AgainException is no longer used as send/receive methods use the Try* pattern and return false in case the operation would block

Error codes

Unused members of the ErrorCode enum have been removed.

  • ErrorCode.InProgres 👉 ErrorCode.InProgress (typo)
  • ErrorCode.ENOENT 👉 ErrorCode.EndpointNotFound
  • ErrorCode.EACCESS 👉 ErrorCode.AccessDenied
  • ErrorCode.EFAULT 👉 ErrorCode.Fault
  • ErrorCode.EINV 👉 ErrorCode.Invalid
  • ErrorCode.EAGAIN 👉 ErrorCode.TryAgain
  • ErrorCode.EINPROGRESS 👉 ErrorCode.InProgress
  • ErrorCode.EPROTONOSUPPORT 👉 ProtocolNotSupported.
  • ErrorCode.ENOTSUP ❎
  • ErrorCode.EADDRINUSE 👉 ErrorCode.AddressAlreadyInUse
  • ErrorCode.EADDRNOTAVAIL 👉 ErrorCode.AddressNotAvailable
  • ErrorCode.ENETDOWN 👉 ErrorCode.NetworkDown
  • ErrorCode.ENOBUFS 👉 ErrorCode.NoBufferSpaceAvailable
  • ErrorCode.EISCONN ❎
  • ErrorCode.EINTR ❎
  • ErrorCode.ENOTCONN 👉 ErrorCode.NotConnected
  • ErrorCode.ECONNREFUSED 👉 ErrorCode.ConnectionRefused
  • ErrorCode.EHOSTUNREACH 👉 ErrorCode.HostUnreachable
  • ErrorCode.ZMQ_HAUSNUMERO 👉 ErrorCode.BaseErrorNumber
  • ErrorCode.EMSGSIZE 👉 ErrorCode.MessageSize
  • ErrorCode.EAFNOSUPPORT 👉 ErrorCode.AddressFamilyNotSupported
  • ErrorCode.ENETUNREACH 👉 ErrorCode.NetworkUnreachable
  • ErrorCode.ECONNABORTED 👉 ErrorCode.ConnectionAborted
  • ErrorCode.ECONNRESET 👉 ErrorCode.ConnectionReset
  • ErrorCode.ETIMEDOUT 👉 ErrorCode.TimedOut
  • ErrorCode.ENETRESET 👉 ErrorCode.NetworkReset
  • ErrorCode.EFSM 👉 ErrorCode.FiniteStateMachine
  • ErrorCode.ENOCOMPATPROTO ❎
  • ErrorCode.ETERM 👉 ErrorCode.ContextTerminated
  • ErrorCode.EMTHREAD 👉 ErrorCode.EmptyThread
  • ErrorCode.EIOEXC ❎
  • ErrorCode.ESOCKET ❎
  • ErrorCode.EMFILE 👉 ErrorCode.TooManyOpenSockets

Miscellaneous

The following items have been obsolete for a long time and their use is very unlikely if you observe compiler warnings. However they are listed here for completeness.

  • Blob 👉 NetMQFrame
  • Actor<T> 👉 NetMQActor (non-generic)
  • IShimHandler<T> 👉 IShimHandler (non-generic)
  • ActorKnownMessages.END_PIPE 👉 NetMQActor.EndShimMessage
  • enum MsgType.Invalid 👉 MsgType.Uninitialised
  • MsgType.Check() 👉 MsgType.IsInitialised
  • SocketEvent 👉 SocketEvents

Full project documentation is available at netmq.readthedocs.org

Clone this wiki locally