Interface Writable<M, O>

send

• send(message: M, ...options: O): Promise<void>

• Sends a single message or a multipart message on the socket. Queues the message immediately if possible, and returns a resolved promise. If the message cannot be queued because the high water mark has been reached, it will wait asynchronously. The promise will be resolved when the message was queued successfully.

  await socket.send("hello world")
  await socket.send(["hello", "world"])
  

  Queueing may fail eventually if the socket has been configured with a sendTimeout.

  A call to send() is guaranteed to return with a resolved promise immediately if the message could be queued directly.

  Only one asynchronously blocking call to send() may be executed simultaneously. If you call send() again on a socket that is in the mute state it will return a rejected promise with an EBUSY error.

  The reason for disallowing multiple send() calls simultaneously is that it could create an implicit queue of unsendable outgoing messages. This would circumvent the socket's sendHighWaterMark. Such an implementation could even exhaust all system memory and cause the Node.js process to abort.

  For most application you should not notice this implementation detail. Only in rare occasions will a call to send() that does not resolve immediately be undesired. Here are some common scenarios:

  • If you wish to send a message, use await send(...). ZeroMQ socket types have been carefully designed to give you the correct blocking behaviour on the chosen socket type in almost all cases:

    • If sending is not possible, it is often better to wait than to continue as if nothing happened. For example, on a Request socket, you can only receive a reply once a message has been sent; so waiting until a message could be queued before continuing with the rest of the program (likely to read from the socket) is required.

    • Certain socket types (such as Router) will always allow queueing messages and await send(...) won't delay any code that comes after. This makes sense for routers, since typically you don't want a single send operation to stop the handling of other incoming or outgoing messages.

  • If you wish to send on an occasionally blocking socket (for example on a Router with the mandatory option set, or on a Dealer) and you're 100% certain that dropping a message is better than blocking, then you can set the sendTimeout option to 0 to effectively force send() to always resolve immediately. Be prepared to catch exceptions if sending a message is not immediately possible.

  • If you wish to send on a socket and messages should be queued before they are dropped, you should implement a simple queue in JavaScript. Such a queue is not provided by this library because most real world applications need to deal with undeliverable messages in more complex ways - for example, they might need to reply with a status message; or first retry delivery a certain number of times before giving up.

  Returns

  Resolved when the message was successfully queued.

  Parameters

  • message: M

    Single message or multipart message to queue for sending.

  • Rest ...options: O

    Any options, if applicable to the socket type (DRAFT only).

  Returns Promise<void>