Struct PacketRc

pub struct PacketRc { /* private fields */ }

A thread-safe shared reference to a Packet.

Although a PacketRc is thread-safe, a panic may occur if multiple threads concurrently write PacketStatus metadata on the inner Packet. Thus, use new_copy_inner() to copy the inner Packet and send the copy to the other thread rather than sharing it between threads.

A PacketRc is a wrapper around a Packet and allows us to support reference counting on Packets while safely sharing them across threads. A clone of a PacketRcs increments the reference count of the shared Packet while dropping the PacketRc decrements the reference count. The shared inner Packet is only dropped when all PacketRcs referring to it are also dropped (i.e., the reference count reaches zero).

The PartialEq implementation on PacketRc compares the pointer values of the wrapped Packet.

PacketRc implements the Deref trait so that all non-associated functions on Packet can be accessed from instances of PacketRc too.

Implementations

impl PacketRc

pub fn new_ipv4_tcp( header: TcpHeader, payload: Payload, priority: FifoPacketPriority, ) -> Self

Creates a thread-safe shared reference to a new Packet using the provided information. Additional references to the Packet can be cheaply obtained by cloning the returned PacketRc. The Packet is dropped when its last PacketRc reference is dropped.

See Packet::new_ipv4_tcp() for more details.

pub fn new_ipv4_udp( src: SocketAddrV4, dst: SocketAddrV4, payload: Bytes, priority: FifoPacketPriority, ) -> Self

Creates a thread-safe shared reference to a new Packet using the provided information. Additional references to the Packet can be cheaply obtained by cloning the returned PacketRc. The Packet is dropped when its last PacketRc reference is dropped.

See Packet::new_ipv4_udp() for more details.

pub fn new_copy_inner(&self) -> Self

Creates a thread-safe shared reference to a new Packet that is created by performing a copy of the provided referenced Packet. This function copies all packet data except the packet payload, which is shared by incrementing its reference count. Additional references to the Packet can be cheaply obtained by cloning the returned PacketRc. The Packet is dropped when its last PacketRc reference is dropped.

pub fn from_raw(packet_ptr: *mut Packet) -> Self

Transfers ownership of the given packet_ptr reference into a new PacketRc object. The provided pointer must have been obtained from a call to the Rust function PacketRc::into_raw() or the C function packet_new_tcp().

Use PacketRc::into_raw() if the returned reference is to be handed back to C code.

Panics

This function panics if the supplied packet pointer is NULL.

Deprecation

This function provides compatibility with the legacy C TCP stack and should be considered deprecated and removed when the legacy C TCP stack is removed.

pub fn into_raw(self) -> *mut Packet

Transfers ownership of the inner Arc reference to the caller while dropping the PacketRc.

To avoid a memory leak, the returned pointer must be either reconstituted into a PacketRc using the Rust function PacketRc::from_raw(), or dropped using the C function packet_unref().

Although this returns a *mut Packet pointer, the packet is not actually mutuable. We return a *mut Packet pointer only to avoid having to change the instnaces of the pointers to const instances in the C network code.

Deprecation

This function provides compatibility with the legacy C TCP stack and should be considered deprecated and removed when the legacy C TCP stack is removed.

Methods from Deref<Target = Packet>

pub fn ipv4_tcp_header(&self) -> Option<TcpHeader>

If the packet is an IPv4 TCP packet, returns a copy of the TCP header in a format defined by the Rust TCP stack. Otherwise, returns None.

Panics

This function panics if the packet was created with packet_new_tcp() in the legacy C API.

pub fn payload(&self) -> Vec<Bytes>

Returns the packet’s payload that was provided at packet creation time. This function allocates a new Vec, but is zero-copy with respect to the payload Bytes.

This function may return a non-empty vector of zero-length Bytes object(s) if zero-length Bytes object(s) were provided at creation time. Thus, it may be helpful to check if the packet has useful payload using payload_len() before calling this function.

pub fn len(&self) -> usize

Returns the total simulated length of the packet, which is the sum of the emulated IP and transport header lengths and the payload length.

pub fn payload_len(&self) -> usize

Returns the total number of payload bytes stored in the packet, which excludes IP and transport header lengths.

pub fn add_status(&self, status: PacketStatus)

Appends the provided packet status to the list of the packet’s status checkpoints.

This function has no effect unless log::Level::Trace is enabled.

pub fn src_ipv4_address(&self) -> SocketAddrV4

Returns the packet’s IPv4 source address and source port.

Panics

This function panics if the source address is not an IPv4 address.

pub fn dst_ipv4_address(&self) -> SocketAddrV4

Returns the packet’s IPv4 destination address and destination port.

Panics

This function panics if the destination address is not an IPv4 address.

pub fn priority(&self) -> FifoPacketPriority

Returns the priority set at packet creation time.

pub fn iana_protocol(&self) -> IanaProtocol

Returns the packet’s iana-assigned protocol type.

Trait Implementations

impl Clone for PacketRc

fn clone(&self) -> PacketRc

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PacketRc

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for PacketRc

type Target = Packet

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl From<Packet> for PacketRc

fn from(packet: Packet) -> Self

Converts to this type from the input type.

impl From<PacketEventData> for PacketRc

fn from(data: PacketEventData) -> Self

Converts to this type from the input type.

impl PartialEq for PacketRc

fn eq(&self, other: &Self) -> bool

Compares the pointer rather than the value of the inner Arc<Packet> object.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for PacketRc