org.apache.pekko.io.UdpManager.scala Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of pekko-actor_2.13 Show documentation

Apache Pekko is a toolkit for building highly concurrent, distributed, and resilient message-driven applications for Java and Scala.

There is a newer version: 1.1.2

Show newest version

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * license agreements; and to You under the Apache License, version 2.0:
 *
 *   https://www.apache.org/licenses/LICENSE-2.0
 *
 * This file is part of the Apache Pekko project, which was derived from Akka.
 */

/*
 * Copyright (C) 2009-2022 Lightbend Inc. 
 */

package org.apache.pekko.io

import org.apache.pekko
import pekko.actor.Props
import pekko.io.Udp._

/**
 * INTERNAL API
 *
 * UdpManager is a facade for simple fire-and-forget style UDP operations
 *
 * UdpManager is obtainable by calling {{{ IO(Udp) }}} (see [[pekko.io.IO]] and [[pekko.io.Udp]])
 *
 * *Warning!* Udp uses [[java.nio.channels.DatagramChannel#send]] to deliver datagrams, and as a consequence if a
 * security manager  has been installed then for each datagram it will verify if the target address and port number are
 * permitted. If this performance overhead is undesirable use the connection style Udp extension.
 *
 * == Bind and send ==
 *
 * To bind and listen to a local address, a [[pekko.io.Udp..Bind]] command must be sent to this actor. If the binding
 * was successful, the sender of the [[pekko.io.Udp.Bind]] will be notified with a [[pekko.io.Udp.Bound]]
 * message. The sender of the [[pekko.io.Udp.Bound]] message is the Listener actor (an internal actor responsible for
 * listening to server events). To unbind the port an [[pekko.io.Tcp.Unbind]] message must be sent to the Listener actor.
 *
 * If the bind request is rejected because the Udp system is not able to register more channels (see the nr-of-selectors
 * and max-channels configuration options in the pekko.io.udp section of the configuration) the sender will be notified
 * with a [[pekko.io.Udp.CommandFailed]] message. This message contains the original command for reference.
 *
 * The handler provided in the [[pekko.io.Udp.Bind]] message will receive inbound datagrams to the bound port
 * wrapped in [[pekko.io.Udp.Received]] messages which contain the payload of the datagram and the sender address.
 *
 * UDP datagrams can be sent by sending [[pekko.io.Udp.Send]] messages to the Listener actor. The sender port of the
 * outbound datagram will be the port to which the Listener is bound.
 *
 * == Simple send ==
 *
 * Udp provides a simple method of sending UDP datagrams if no reply is expected. To acquire the Sender actor
 * a SimpleSend message has to be sent to the manager. The sender of the command will be notified by a SimpleSenderReady
 * message that the service is available. UDP datagrams can be sent by sending [[pekko.io.Udp.Send]] messages to the
 * sender of SimpleSenderReady. All the datagrams will contain an ephemeral local port as sender and answers will be
 * discarded.
 */
private[io] class UdpManager(udp: UdpExt)
    extends SelectionHandler.SelectorBasedManager(udp.settings, udp.settings.NrOfSelectors) {

  def receive = workerForCommandHandler {
    case b: Bind =>
      val commander = sender() // cache because we create a function that will run asynchly
      registry => Props(classOf[UdpListener], udp, registry, commander, b)

    case s: SimpleSender =>
      val commander = sender() // cache because we create a function that will run asynchly
      registry => Props(classOf[UdpSender], udp, registry, commander, s.options)
  }

}