Documentation
¶
Overview ¶
Package ring wraps RTE ring library.
Please refer to DPDK Programmer's Guide for reference and caveats.
Index ¶
- Constants
- Variables
- func GetMemSize(count uint) (int, error)
- func TelemetryInit(prefix string)
- type Option
- type Ring
- func (r *Ring) Cap() uint
- func (r *Ring) Count() uint
- func (r *Ring) Dequeue() (unsafe.Pointer, bool)
- func (r *Ring) DequeueBulk(obj []unsafe.Pointer) (n, avail uint32)
- func (r *Ring) DequeueBurst(obj []unsafe.Pointer) (n, avail uint32)
- func (r *Ring) Enqueue(obj unsafe.Pointer) bool
- func (r *Ring) EnqueueBulk(obj []unsafe.Pointer) (n, free uint32)
- func (r *Ring) EnqueueBurst(obj []unsafe.Pointer) (n, free uint32)
- func (r *Ring) Free()
- func (r *Ring) FreeCount() uint
- func (r *Ring) Init(name string, count uint, opts ...Option) error
- func (r *Ring) IsEmpty() bool
- func (r *Ring) IsFull() bool
- func (r *Ring) McDequeue() (unsafe.Pointer, bool)
- func (r *Ring) McDequeueBulk(obj []unsafe.Pointer) (n, avail uint32)
- func (r *Ring) McDequeueBurst(obj []unsafe.Pointer) (n, avail uint32)
- func (r *Ring) MpEnqueue(obj unsafe.Pointer) bool
- func (r *Ring) MpEnqueueBulk(obj []unsafe.Pointer) (n, free uint32)
- func (r *Ring) MpEnqueueBurst(obj []unsafe.Pointer) (n, free uint32)
- func (r *Ring) Name() string
- func (r *Ring) ScDequeue() (unsafe.Pointer, bool)
- func (r *Ring) ScDequeueBulk(obj []unsafe.Pointer) (n, avail uint32)
- func (r *Ring) ScDequeueBurst(obj []unsafe.Pointer) (n, avail uint32)
- func (r *Ring) Size() uint
- func (r *Ring) SpEnqueue(obj unsafe.Pointer) bool
- func (r *Ring) SpEnqueueBulk(obj []unsafe.Pointer) (n, free uint32)
- func (r *Ring) SpEnqueueBurst(obj []unsafe.Pointer) (n, free uint32)
Constants ¶
const ( // SingleConsumer specifies that default dequeue operation will // exhibit 'single-consumer' behaviour. SingleConsumer uint = C.RING_F_SC_DEQ // SingleProducer specifies that default enqueue operation will // exhibit 'single-producer' behaviour. SingleProducer = C.RING_F_SP_ENQ // ExactSize specifies how to handle ring size during Create/Init. // Ring is to hold exactly requested number of entries. Without // this flag set, the ring size requested must be a power of 2, // and the usable space will be that size - 1. With the flag, the // requested size will be rounded up to the next power of two, but // the usable space will be exactly that requested. Worst case, if // a power-of-2 size is requested, half the ring space will be // wasted. ExactSize = C.RING_F_EXACT_SZ )
Variables ¶
var ( OptSC = OptFlag(SingleConsumer) OptSP = OptFlag(SingleProducer) OptES = OptFlag(ExactSize) )
Shortcuts for ring creation flags.
Functions ¶
func GetMemSize ¶
GetMemSize calculates the memory size needed for a ring.
This function returns the number of bytes needed for a ring, given the number of elements in it. This value is the sum of the size of the structure rte_ring and the size of the memory needed by the objects pointers. The value is aligned to a cache line size.
count should be power of 2. If that is not the case, EINVAL error will be returned.
func TelemetryInit ¶ added in v0.0.12
func TelemetryInit(prefix string)
TelemetryInit initializes telemetry callbacks for rings. Specify prefix for cmd path to avoid conflicts in the future. "/ring" is the good candidate for a prefix.
Types ¶
type Option ¶
type Option struct {
// contains filtered or unexported fields
}
Option alters ring behaviour.
func OptAlign ¶ added in v0.0.7
OptAlign specifies the alignment requirement for allocation using malloc. Not used in Create.
type Ring ¶
type Ring C.struct_rte_ring
Ring is a fixed-size queue, implemented as a table of pointers. Head and tail pointers are modified atomically, allowing concurrent access to it. It has the following features:
* FIFO (First In First Out)
* Maximum size is fixed; the pointers are stored in a table.
* Lockless implementation.
* Multi- or single-consumer dequeue.
* Multi- or single-producer enqueue.
* Bulk dequeue.
* Bulk enqueue. Note: the ring implementation is not preemptible. Refer to Programmer's guide/Environment Abstraction Layer/Multiple pthread/Known Issues/rte_ring for more information.
func Create ¶
Create creates new ring named name in memory.
This function uses rte_memzone_reserve() to allocate memory. Then it calls rte_ring_init() to initialize an empty ring.
The new ring size is set to count, which must be a power of two. Water marking is disabled by default. The real usable ring size is count-1 instead of count to differentiate a free ring from an empty ring.
The ring is added in RTE_TAILQ_RING list.
func Lookup ¶
Lookup searches a ring from its name in RTE_TAILQ_RING, i.e. among those created with Create.
func New ¶
New allocates and initializes Ring in Go memory. It allocates a slice of bytes with enough length to hold a Ring with requested parameters. Then slice is casted to Ring and initialized with Init.
Please note that OptSocket is irrelevant in this case and is unused if specified.
func NewEAL ¶ added in v0.0.7
NewEAL allocates and initializes Ring in EAL memory. It allocates a memory with rte_zmalloc_socket with enough length to hold a Ring with requested parameters. Then this pointer is casted to Ring and initialized with Init.
func (*Ring) DequeueBulk ¶
DequeueBulk dequeues objects into given slice of pointers. Returns number of dequeued objects (either 0 or len(obj)) and amount of remaining ring entries in the ring after the enqueue operation has finished.
func (*Ring) DequeueBurst ¶
DequeueBurst dequeues objects into given slice of pointers. Returns number of dequeued objects and amount of remaining ring entries in the ring after the enqueue operation has finished. after the enqueue operation has finished.
func (*Ring) EnqueueBulk ¶
EnqueueBulk enqueues given objects from slice into Ring. Returns number of enqueued objects (either 0 or len(obj)) and amount of space in the ring after the enqueue operation has finished.
func (*Ring) EnqueueBurst ¶
EnqueueBurst enqueues given objects from slice into Ring. Returns number of enqueued objects and amount of space in the ring after the enqueue operation has finished.
func (*Ring) Free ¶
func (r *Ring) Free()
Free deallocates all memory used by the ring.
This function must be called only if r was created with Create or NewEAL.
func (*Ring) Init ¶
Init initializes a ring structure in memory. The size of the memory area must be large enough to store the ring structure and the object table. It is advised to use GetMemSize() to get the appropriate size.
The ring size is set to count, which must be a power of two. Water marking is disabled by default. The real usable ring size is count-1 instead of count to differentiate a free ring from an empty ring.
The ring is not added in RTE_TAILQ_RING global list. Indeed, the memory given by the caller may not be shareable among dpdk processes.
func (*Ring) McDequeueBulk ¶
McDequeueBulk dequeues objects into given slice of pointers. Returns number of dequeued objects (either 0 or len(obj)) and amount of remaining ring entries in the ring after the enqueue operation has finished.
func (*Ring) McDequeueBurst ¶
McDequeueBurst dequeues objects into given slice of pointers. Returns number of dequeued objects and amount of remaining ring entries in the ring after the enqueue operation has finished. after the enqueue operation has finished.
func (*Ring) MpEnqueueBulk ¶
MpEnqueueBulk enqueues given objects from slice into Ring. Returns number of enqueued objects (either 0 or len(obj)) and amount of space in the ring after the enqueue operation has finished.
func (*Ring) MpEnqueueBurst ¶
MpEnqueueBurst enqueues given objects from slice into Ring. Returns number of enqueued objects and amount of space in the ring after the enqueue operation has finished.
func (*Ring) ScDequeueBulk ¶
ScDequeueBulk dequeues objects into given slice of pointers. Returns number of dequeued objects (either 0 or len(obj)) and amount of remaining ring entries in the ring after the enqueue operation has finished.
func (*Ring) ScDequeueBurst ¶
ScDequeueBurst dequeues objects into given slice of pointers. Returns number of dequeued objects and amount of remaining ring entries in the ring after the enqueue operation has finished. after the enqueue operation has finished.
func (*Ring) Size ¶
Size returns the size of the ring.
NOTE: this is not the same as the usable space in the ring. To query that use Cap().
func (*Ring) SpEnqueueBulk ¶
SpEnqueueBulk enqueues given objects from slice into Ring. Returns number of enqueued objects (either 0 or len(obj)) and amount of space in the ring after the enqueue operation has finished.
Source Files