event

Documentation

Overview

Package event provides access to system-level event file descriptors that act as semaphores and notification mechanism to facilitate AF_PACKET network traffic capture. This is achieved either via conventional recvfrom() operations (per-packet retrieval in afpacket/afpacket) or via PPOLL and the kernel ring buffer (per-block retrieval in afpacket/afring). In the latter case, a highly optimized assembler implementation is used (for AMD64 / ARM64 architectures) in order to maximize throughput (by releasing resources as early as possible for the next poll operation).

Index

• Variables
• type EvtData
• type EvtFileDescriptor
  • func New() (EvtFileDescriptor, error)
  • func (e EvtFileDescriptor) ReadEvent() (EvtData, error)
  • func (e EvtFileDescriptor) Signal(data EvtData) error
• type Handler
  • func NewMockHandler() (*Handler, *socket.MockFileDescriptor, error)
  • func (p *Handler) GetSocketStats() (socket.TPacketStats, error)
  • func (p *Handler) Poll(events int16) (hasEvent bool, errno unix.Errno)
  • func (p *Handler) Recvfrom(buf []byte, flags int) (int, uint8, error)
• type MockHandler
  • func ToMockHandler(h *Handler) *MockHandler
  • func (m *MockHandler) HasPackets() bool
  • func (m *MockHandler) SignalAvailableData() error

Variables

var (

	// SignalUnblock ends any ongoing PPOLL syscall  (similar to a timeout)
	SignalUnblock = EvtData{1, 0, 0, 0, 0, 0, 0, 0}

	// SignalStop causes the capture to stop
	SignalStop = EvtData{0, 0, 0, 0, 0, 0, 0, 1}
)

Types

type EvtData

type EvtData [8]byte

EvtData denotes the data sent / received during an event

type EvtFileDescriptor

type EvtFileDescriptor int

EvtFileDescriptor denotes a system-level event file descriptor

func New

func New() (EvtFileDescriptor, error)

New instantiates a new non-blocking event file descriptor

func (EvtFileDescriptor) ReadEvent

func (e EvtFileDescriptor) ReadEvent() (EvtData, error)

ReadEvent reads the event data from the event file descriptor

func (EvtFileDescriptor) Signal

func (e EvtFileDescriptor) Signal(data EvtData) error

Signal sends an event via the event file descriptor

type Handler

type Handler struct {

	// Efd denotes the event file descriptor of this handler
	Efd EvtFileDescriptor

	// Fd denotes the socket file descriptor of this handler
	Fd socket.FileDescriptor
	// contains filtered or unexported fields
}

Handler wraps a socket file descriptor and an event file descriptor in a single instance. In addition, a (unexported) mock file descriptor allows for mocking the entire handler without having to manipulate / distinguish from the caller side

func NewMockHandler

func NewMockHandler() (*Handler, *socket.MockFileDescriptor, error)

NewMockHandler instantiates a new mock Handler (wrapping a regular one)

func (*Handler) GetSocketStats

func (p *Handler) GetSocketStats() (socket.TPacketStats, error)

GetSocketStats returns (and resets) socket / traffic statistics

func (*Handler) Poll

func (p *Handler) Poll(events int16) (hasEvent bool, errno unix.Errno)

Poll polls (blocking, hence no timeout) for events on the file descriptor and the event file descriptor (waiting for a POLLIN event).

func (*Handler) Recvfrom

func (p *Handler) Recvfrom(buf []byte, flags int) (int, uint8, error)

Recvfrom retrieves data directly from the socket

type MockHandler

type MockHandler Handler

MockHandler wraps a regular Handler to allow defining new methods on top of it to facilitate mocking without having to rely on interfaces (and actually provide mocking as close to the original implementation as possible)

func ToMockHandler

func ToMockHandler(h *Handler) *MockHandler

ToMockHandler converts an existing Handler pointer variable to an equivalent MockHandler

func (*MockHandler) HasPackets

func (m *MockHandler) HasPackets() bool

HasPackets returns if there are packets in the underlying mock socket

func (*MockHandler) SignalAvailableData

func (m *MockHandler) SignalAvailableData() error

SignalAvailableData sets the semaphore of the underlying event file descriptor, indicating that data is available (and releasing the block)