> For the complete documentation index, see [llms.txt](https://pcap.ardikars.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pcap.ardikars.com/packet-structure/packet-buffer.md).

# Packet Buffer

This buffer use network-byte-order (big endian) by default.

#### Using Packet Buffer.

* Allocate and Deallocate buffer

```java
final Pcap pcap = ..;
// allocate 8 bytes memory block.
final PacketBuffer buffer = pcap.allocate(PacketBuffer.class).capacity(8);

// deallocate ( free buffer).
assert true == buffer.release();
// double free is not allowed.
assert false == buffer.release();
```

* Slice and Unslice buffer

```java
// allocate 8 bytes memory block.
final PacketBuffer buffer = pcap.allocate(PacketBuffer.class).capacity(8);
final PacketBuffer sliced = buffer.slice();
final PacketBuffer unSliced = ((PacketBuffer.Sliced) sliced).unSlice();
assert buffer != sliced;
assert buffer == unSliced;
// Whatever you do with either sliced or unSliced buffer will affect the original buffer.
// for example when calling release() on the sliced buffer.
assert true == sliced.release();
assert false == buffer.release();
assert false == unSliced.release();
```

**What happen if I forget to call release() before it's garbage collected?**

PacketBuffer uses phantom reference for handling that case. Off-heap (native) buffer will be freed automatically when the object that wraps the off-heap buffer is garbage collected. Instead of waiting for unused buffer object garbage collected, you can free the off-heap buffer immediately by calling release() to avoid a large amount of unused off-heap memory.

You can enable memory leak detection by setting the properties "pcap.leakDetection" to "true". It can be useful to find where is the buffer that you forgot to release.

**What happen when I read/write (accessing) freed/closed buffer?**

MemoryAccessException will be thrown when you are trying to access the freed/closed buffer.

* Set/Get value from the buffer

```java
final Pcap pcap = ..;
// allocate 8 bytes memory block.
final PacketBuffer buffer = pcap.allocate(PacketBuffer.class).capacity(8);

buffer.setInt(0, 10);
buffet.setInt(4, 20);

assert 10 == buffer.getInt(0);
assert 20 == buffer.getInt(4);

assert true = buffer.release();
```

* Write/Read value from the buffer

```java
final Pcap pcap = ..;
// allocate 8 bytes memory block.
final PacketBuffer buffer = pcap.allocate(PacketBuffer.class).capacity(8);
assert 0 == buffer.readerIndex();
assert 0 == buffer.writerIndex();

buffer.writeInt(10);
assert 0 == buffer.readerIndex();
assert 4 == buffer.writerIndex();

buffer.writeInt(20);
assert 0 == buffer.readerIndex();
assert 8 == buffer.writerIndex();

assert 10 == buffer.readInt();
assert 4 == buffer.readerIndex();
assert 8 == buffer.writerIndex();

assert 20 == buffer.readInt();
assert 8 == buffer.readerIndex();
assert 8 == buffer.writerIndex();

assert true = buffer.release();
```

* Using PacketBuffer for nextEx call

```java
final Pcap pcap = ..;
final PacketHeader header = pcap.allocate(PacketHeader.class);
// no need to call buffer.capacity(..); no malloc needed.
final PacketBuffer buffer = pcap.allocate(PacketBuffer.class);

pcap.nextEx(header, buffer);

// buffer is not guaranteed to be valid after the next call
// copy the buffer if necessary
final copied = buffer.copy();
assert true == copied.release();

// no need to call buffer.release();
```