Packet Buffer

Used to wrap low-lavel memory address (native buffer/off-heap buffer).

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

Using Packet Buffer.

• Allocate and Deallocate buffer

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

// 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

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

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

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();