net.i2p.router.transport.udp

## Class UDPPacket

- java.lang.Object
- - net.i2p.router.transport.udp.UDPPacket

- All Implemented Interfaces:
    CDPQEntry, CDQEntry, PQEntry

      class UDPPacket
      extends Object
      implements CDPQEntry

  UDP packet wrapper with caching and metadata support. This class wraps standard DatagramPacket objects and adds I2P-specific metadata for efficient packet handling and reuse. It implements an object cache pattern to reduce garbage collection overhead and improve performance in high-throughput scenarios. Core Features:
  - Packet wrapping with metadata preservation
  - Object caching for reuse and GC reduction
  - Priority-based queuing and processing
  - Fragmentation and reassembly support
  - Bandwidth reservation and throttling integration
  - Timestamp and routing metadata
  Caching Strategy:
  - Internal object pool for packet reuse
  - Cache size limits and eviction policies
  - Thread-safe cache operations
  - Memory-efficient packet allocation
  Metadata Support:
  - Message type and protocol information
  - Priority levels for QoS handling
  - Fragment identification and sequencing
  - Bandwidth allocation tracking
  - Routing and forwarding information
  Performance Optimizations:
  - Minimal object creation overhead
  - Efficient data copying and cloning
  - Cache-friendly packet lifecycle management
  - Reduced garbage collection pressure

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `IV_SIZE` Size of initialization vector in bytes.
    `static int` | `MAC_SIZE` Size of MAC (Message Authentication Code) in bytes.
    `(package private) static int` | `MAX_PACKET_SIZE` Maximum UDP packet size accepted.
    `static int` | `MAX_PAYLOAD_TYPE`
    `static int` | `PAYLOAD_TYPE_DATA`
    `static int` | `PAYLOAD_TYPE_RELAY_INTRO`
    `static int` | `PAYLOAD_TYPE_RELAY_REQUEST`
    `static int` | `PAYLOAD_TYPE_RELAY_RESPONSE`
    `static int` | `PAYLOAD_TYPE_SESSION_CONFIRMED`
    `static int` | `PAYLOAD_TYPE_SESSION_CREATED`
    `static int` | `PAYLOAD_TYPE_SESSION_DESTROY`
    `static int` | `PAYLOAD_TYPE_SESSION_REQUEST`
    `static int` | `PAYLOAD_TYPE_TEST`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static UDPPacket` | `acquire(RouterContext ctx, boolean inbound)` Acquires a UDPPacket instance, either from the cache or by creating a new instance.
    `static void` | `clearCache()` Clears the internal packet cache if caching is enabled.
    `void` | `drop()` Convenience method to release the packet.
    `FIFOBandwidthLimiter.Request` | `getBandwidthRequest()` Returns the current bandwidth request associated with this packet.
    `long` | `getBegin()` Gets the packet initialization timestamp in milliseconds.
    `long` | `getEnqueueTime()` Gets the time the packet was enqueued.
    `(package private) int` | `getFragmentCount()`
    `long` | `getLifetime()` Returns how long this packet has existed since initialization.
    `int` | `getMarkedType()` Gets the currently marked type of the packet.
    `(package private) int` | `getMessageType()`
    `DatagramPacket` | `getPacket()` Gets the underlying `DatagramPacket`.
    `int` | `getPriority()` Gets the packet priority.
    `(package private) RemoteHostId` | `getRemoteHost()` Lazily obtains the `RemoteHostId` representing the sender's address and port.
    `long` | `getSeqNum()` Gets the packet sequence number.
    `(package private) long` | `getTimeSinceReceived()` Returns the amount of time elapsed since the packet was received.
    `void` | `markType(int type)` Marks the packet with a custom type for internal identification.
    `static String` | `payloadTypeToString(int type)` Converts payload type integer constant to human-readable string.
    `(package private) void` | `received()` Marks the packet as received, recording the current time.
    `static void` | `reduceCacheSize()` Reduces cache size under memory pressure.
    `void` | `release()` Releases this packet back to the object cache and aborts any outstanding bandwidth request.
    `void` | `requestOutboundBandwidth()` Requests outbound bandwidth for sending this packet.
    `void` | `resetBegin()` Resets the initialization timestamp to current time.
    `void` | `setEnqueueTime(long now)` Sets the enqueue time timestamp, indicating when the packet was queued for processing.
    `(package private) void` | `setFragmentCount(int count)`
    `(package private) void` | `setMessageType(int type)`
    `void` | `setPriority(int pri)` Sets the packet priority.
    `void` | `setSeqNum(long num)` Sets the packet sequence number.
    `String` | `toString()` Returns a detailed string representation of this packet, including address, size, priority, message and mark types, fragment counts, and timing information.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### IV_SIZE

          public static final int IV_SIZE

      Size of initialization vector in bytes.
      See Also:
        Constant Field Values

    - #### MAC_SIZE

          public static final int MAC_SIZE

      Size of MAC (Message Authentication Code) in bytes.
      See Also:
        Constant Field Values

    - #### MAX_PACKET_SIZE

          static final int MAX_PACKET_SIZE

      Maximum UDP packet size accepted. Packets of this size are assumed truncated. Size allows for some legacy packet bugs and includes overhead.
      See Also:
        Constant Field Values

    - #### MAX_PAYLOAD_TYPE

          public static final int MAX_PAYLOAD_TYPE

      See Also:
        Constant Field Values

    - #### PAYLOAD_TYPE_DATA

          public static final int PAYLOAD_TYPE_DATA

      See Also:
        Constant Field Values

    - #### PAYLOAD_TYPE_RELAY_INTRO

          public static final int PAYLOAD_TYPE_RELAY_INTRO

      See Also:
        Constant Field Values

    - #### PAYLOAD_TYPE_RELAY_REQUEST

          public static final int PAYLOAD_TYPE_RELAY_REQUEST

      See Also:
        Constant Field Values

    - #### PAYLOAD_TYPE_RELAY_RESPONSE

          public static final int PAYLOAD_TYPE_RELAY_RESPONSE

      See Also:
        Constant Field Values

    - #### PAYLOAD_TYPE_SESSION_CONFIRMED

          public static final int PAYLOAD_TYPE_SESSION_CONFIRMED

      See Also:
        Constant Field Values

    - #### PAYLOAD_TYPE_SESSION_CREATED

          public static final int PAYLOAD_TYPE_SESSION_CREATED

      See Also:
        Constant Field Values

    - #### PAYLOAD_TYPE_SESSION_DESTROY

          public static final int PAYLOAD_TYPE_SESSION_DESTROY

      See Also:
        Constant Field Values

    - #### PAYLOAD_TYPE_SESSION_REQUEST

          public static final int PAYLOAD_TYPE_SESSION_REQUEST

      See Also:
        Constant Field Values

    - #### PAYLOAD_TYPE_TEST

          public static final int PAYLOAD_TYPE_TEST

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### acquire

          public static UDPPacket acquire(RouterContext ctx,
                                          boolean inbound)

      Acquires a UDPPacket instance, either from the cache or by creating a new instance. Initializes the packet for use.
      Parameters:
        `ctx` - RouterContext for timing and logging
        `inbound` - true if this packet is inbound, false if outbound (currently unused)
      Returns:
        initialized UDPPacket instance

    - #### clearCache

          public static void clearCache()

      Clears the internal packet cache if caching is enabled. Useful to free resources, e.g. on shutdown or restart.

    - #### drop

          public void drop()

      Convenience method to release the packet.
      Specified by:
        `drop` in interface `CDQEntry`

    - #### getBandwidthRequest

          public FIFOBandwidthLimiter.Request getBandwidthRequest()

      Returns the current bandwidth request associated with this packet.
      Returns:
        bandwidth request object, or null if none exists

    - #### getBegin

          public long getBegin()

      Gets the packet initialization timestamp in milliseconds.
      Returns:
        time in ms when packet was initialized

    - #### getEnqueueTime

          public long getEnqueueTime()

      Gets the time the packet was enqueued.
      Specified by:
        `getEnqueueTime` in interface `CDQEntry`
      Returns:
        enqueue timestamp in milliseconds

    - #### getFragmentCount

          int getFragmentCount()

    - #### getLifetime

          public long getLifetime()

      Returns how long this packet has existed since initialization.
      Returns:
        lifetime in milliseconds

    - #### getMarkedType

          public int getMarkedType()

      Gets the currently marked type of the packet.
      Returns:
        mark type integer or -1 if none set

    - #### getMessageType

          int getMessageType()

    - #### getPacket

          public DatagramPacket getPacket()

      Gets the underlying `DatagramPacket`.
      Returns:
        datagram packet instance
      Throws:
        `IllegalStateException` - if the packet has been released

    - #### getPriority

          public int getPriority()

      Gets the packet priority.
      Specified by:
        `getPriority` in interface `PQEntry`
      Returns:
        packet priority as integer

    - #### getRemoteHost

          RemoteHostId getRemoteHost()

      Lazily obtains the `RemoteHostId` representing the sender's address and port. This is initialized once per packet and cached thereafter.
      Returns:
        remote host identifier or null if address unavailable

    - #### getSeqNum

          public long getSeqNum()

      Gets the packet sequence number.
      Specified by:
        `getSeqNum` in interface `PQEntry`
      Returns:
        sequence number

    - #### getTimeSinceReceived

          long getTimeSinceReceived()

      Returns the amount of time elapsed since the packet was received.
      Returns:
        milliseconds since received, or 0 if never received

    - #### markType

          public void markType(int type)

      Marks the packet with a custom type for internal identification.
      Parameters:
        `type` - integer representing a mark type

    - #### payloadTypeToString

          public static String payloadTypeToString(int type)

      Converts payload type integer constant to human-readable string.
      Parameters:
        `type` - the payload type constant
      Returns:
        descriptive string of payload type

    - #### received

          void received()

      Marks the packet as received, recording the current time.

    - #### reduceCacheSize

          public static void reduceCacheSize()

      Reduces cache size under memory pressure.

    - #### release

          public void release()

      Releases this packet back to the object cache and aborts any outstanding bandwidth request. Safe to call multiple times. After release, accessing the packet will log errors.

    - #### requestOutboundBandwidth

          public void requestOutboundBandwidth()

      Requests outbound bandwidth for sending this packet. The bandwidth request is tracked and can be aborted if the packet is released early.

    - #### resetBegin

          public void resetBegin()

      Resets the initialization timestamp to current time.

    - #### setEnqueueTime

          public void setEnqueueTime(long now)

      Sets the enqueue time timestamp, indicating when the packet was queued for processing.
      Specified by:
        `setEnqueueTime` in interface `CDQEntry`
      Parameters:
        `now` - enqueue time in milliseconds

    - #### setFragmentCount

          void setFragmentCount(int count)

    - #### setMessageType

          void setMessageType(int type)

    - #### setPriority

          public void setPriority(int pri)

      Sets the packet priority.
      Parameters:
        `pri` - priority level to assign

    - #### setSeqNum

          public void setSeqNum(long num)

      Sets the packet sequence number.
      Specified by:
        `setSeqNum` in interface `PQEntry`
      Parameters:
        `num` - sequence number to set

    - #### toString

          public String toString()

      Returns a detailed string representation of this packet, including address, size, priority, message and mark types, fragment counts, and timing information. For logging and debugging purposes.
      Overrides:
        `toString` in class `Object`