Expand description
A Router routes PacketRcs between PacketDevices and the
simulated network, enforcing configured send/receive rate limits on the
interfaces and the upstream/downstream links to a modeled network provider.
The Router is responsible for actually moving packets around between
sockets and the simulated network. It initiates packet forwarding and
internally schedules tasks to ensure that packets are continually forwarded
over time without exceeding the configured RateLimits.
The Router implemented here is doing the job of multiple real world
physical components, rather than being a one-to-one mapping to a known
network component. It is managing sending from a physical network interface
card at a certain speed, and also it is managing the first-hop router device
that the network interface card is attached to, shaping traffic, and using a
codel queue to aggregate all its ports up through a single upstream link.
PacketDevices are registered using Router::attach_packet_device,
assigning an Ipv4Addr to it. The address provided by the caller will
later be passed to RouterContext::get_packet_device_fn to obtain the
underlying object that implements the PacketDevice trait. This packet
device supplies the router with a stream of packets (through its
implementation of PacketDevice::pop) that will be forwarded to the
network, and it acts as a sink for incoming packets with a destination
address matching the packet device’s address.
Ipv4Addr::LOCALHOST has special meaning, and it is expected that a
packet device will be registered at this address. The router uses the device
as the loopback device, applying its rate limits for local packets being
sent from any device.
The Router operates its own event management queues and its scheduler
must be run at appropriate times to faciliate the routing process.
Router::run must be called with event RouterEvent::DeviceInterrupt
when a packet device changes state from empty to non-empty, to alert an idle
router to start forwarding packets from that device. Router::run must be
called with event RouterEvent::PacketArrival when a packet arrives from
the simulated network. Finally, if Router::run returns an
EmulatedTime, then Router::run must be called with event
RouterEvent::Wakeup at the specified time. All other routing tasks are
handled internally.
The Router is designed to avoid directly relying on Shadow runtime
components and to be easy to test with unit tests. This is enabled through
the RouterContext object, which defines the minimal external API the
router needs to function. This context must be provided when calling
Router::run.
A variety of queues are used to model rate limits, as shown below. Each tx queue and rx queue is a lossy rate-limited queue that can drop packets if it becomes bloated (e.g., if we are allowed to push() to a queue at a faster rate than we are allowed to pop() from it based on the configured rate limits). Note, all pop() and push() actions are carried out by the router, not the individual components listed here.
+–––––––+ +–––––––+ | PacketDevice | | PacketDevice | +–––––––+ +–––––––+ | | Event::DeviceInterrupt Event::DeviceInterrupt | | V push() V push() +———–+ +———–+ | Interface | | Interface | | tx queue | | tx queue | +———–+ +———–+ | | pop() @ dev tx rate limit pop() @ dev tx rate limit | | +–––––––+—————+ | V push() +—————––+ | Global router | | tx queue | +—————––+ | pop() @ upstream tx rate limit | V Context::send_packet_fn() +––––––––––+ | packets to network | +––––––––––+ ||| core link ||| models latency, packet loss ||| unlimited bandwidth VVV +–––––––––––+ | packets from network | +–––––––––––+ | RouterEvent::PacketArrival | V push() +—————––+ | Global router | | rx queue | +—————––+ | pop() @ downstream rx rate limit | +–––––––+—————+ | | V push() V push() +———–+ +———–+ | Interface | | Interface | | rx queue | | rx queue | +———–+ +———–+ | | pop() @ dev rx rate limit pop() @ dev rx rate limit | | V push() V push() +–––––––+ +–––––––+ | PacketDevice | | PacketDevice | +–––––––+ +–––––––+
Note: the cross-device loopback process is not shown above.
Structs§
- Context
- Generalizes the runtime state needed to run the router.
- Router
- A
RouterroutesPacketRcs betweenPacketDevices and the simulated network, enforcing configured send/receive rate limits on the interfaces and the upstream/downstream links to a modeled network provider.
Enums§
Type Aliases§
- Router
Context - An alias for the router context, to clearly separate it from other contexts
in the simulator. Code external to the router should probably prefer this
RouterContextto theContextsyntax for clarity. - Router
Event - An alias for a router event, to clearly separate it from other events in the
simulator. Code external to the router should probably prefer this
RouterEventto theEventsyntax for clarity.