Mac Developer Library

Developer

IODataQueue Class Reference

Options
Deployment Target:

On This Page
Language:

IODataQueue

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.
Deprecated in OS X v10.10.

A generic queue designed to pass data from the kernel to a user process.

The IODataQueue class is designed to allow kernel code to queue data to a user process. IODataQueue objects are designed to be used in a single producer / single consumer situation. As such, there are no locks on the data itself. Because the kernel enqueue and user-space dequeue methods follow a strict set of guidelines, no locks are necessary to maintain the integrity of the data struct.

Each data entry can be variable sized, but the entire size of the queue data region (including overhead for each entry) must be specified up front.

In order for the IODataQueue instance to notify the user process that data is available, a notification mach port must be set. When the queue is empty and a new entry is added, a message is sent to the specified port.

User client code exists in the IOKit framework that facilitates the creation of the receive notification port as well as the listen process for new data available notifications.

In order to make the data queue memory available to a user process, the method getMemoryDescriptor() must be used to get an IOMemoryDescriptor instance that can be mapped into a user process. Typically, the clientMemoryForType() method on an IOUserClient instance will be used to request the IOMemoryDescriptor and then return it to be mapped into the user process.

  • Enqueues a new entry on the queue.

    Declaration

    C++

    virtual Boolean enqueue( void *data, UInt32dataSize);

    Parameters

    data

    Pointer to the data to be added to the queue.

    dataSize

    Size of the data pointed to by data.

    Return Value

    Returns true on success and false on failure. Typically failure means that the queue is full.

    Discussion

    This method adds a new data entry of dataSize to the queue. It sets the size parameter of the entry pointed to by the tail value and copies the memory pointed to by the data parameter in place in the queue. Once that is done, it moves the tail to the next available location. When attempting to add a new entry towards the end of the queue and there isn't enough space at the end, it wraps back to the beginning.

    If the queue is empty when a new entry is added, sendDataAvailableNotification() is called to send a message to the user process that data is now available.

  • Returns a memory descriptor covering the IODataQueueMemory region.

    Declaration

    C++

    virtual IOMemoryDescriptor *getMemoryDescriptor();

    Return Value

    Returns a newly allocated IOMemoryDescriptor for the IODataQueueMemory region. Returns zero on failure.

    Discussion

    The IOMemoryDescriptor instance returned by this method is intended to be mapped into a user process. This is the memory region that the IODataQueueClient code operates on.

  • Initializes an IODataQueue instance with the capacity specified in the size parameter.

    Declaration

    C++

    virtual Boolean initWithCapacity( UInt32size);

    Parameters

    size

    The size of the data queue memory region.

    Return Value

    Returns true on success and false on failure.

    Discussion

    The actual size of the entire data queue memory region (to be shared into a user process) is equal to the capacity plus the IODataQueueMemory overhead. This overhead value can be determined from the DATA_QUEUE_MEMORY_HEADER_SIZE macro in <IOKit/IODataQueueShared.h>. The size of the data queue memory region must include space for the overhead of each IODataQueueEntry. This entry overhead can be determined from the DATA_QUEUE_ENTRY_HEADER_SIZE macro in <IOKit/IODataQueueShared.h>.

  • Initializes an IODataQueue instance with the specified number of entries of the given size.

    Declaration

    C++

    virtual Boolean initWithEntries( UInt32numEntries, UInt32entrySize);

    Parameters

    numEntries

    Number of entries to allocate space for.

    entrySize

    Size of each entry.

    Return Value

    Reeturns true on success and false on failure.

    Discussion

    This method will initialize an IODataQueue instance with enough capacity for numEntries of entrySize. It does account for the IODataQueueEntry overhead for each entry. Note that the numEntries and entrySize are simply used to determine the data region size. They do not actually restrict the size of number of entries that can be added to the queue.

    This method allocates a new IODataQueue instance and then calls initWithEntries() with the given numEntries and entrySize parameters.

  • Sends a dataAvailableNotification message to the specified mach port.

    Declaration

    C++

    virtual void sendDataAvailableNotification();

    Discussion

    This method sends a message to the mach port passed to setNotificationPort(). It is used to indicate that data is available in the queue.

  • Creates a simple mach message targeting the mach port specified in port.

    Declaration

    C++

    virtual void setNotificationPort( mach_port_tport);

    Parameters

    port

    The mach port to target with the notification message.

    Discussion

    This message is sent when data is added to an empty queue. It is to notify a user process that new data has become available.

  • Static method that creates a new IODataQueue instance with the capacity specified in the size parameter.

    Declaration

    C++

    static IODataQueue *withCapacity( UInt32size);

    Parameters

    size

    The size of the data queue memory region.

    Return Value

    Returns the newly allocated IODataQueue instance. Zero is returned on failure.

    Discussion

    The actual size of the entire data queue memory region (to be shared into a user process) is equal to the capacity plus the IODataQueueMemory overhead. This overhead value can be determined from the DATA_QUEUE_MEMORY_HEADER_SIZE macro in <IOKit/IODataQueueShared.h>. The size of the data queue memory region must include space for the overhead of each IODataQueueEntry. This entry overhead can be determined from the DATA_QUEUE_ENTRY_HEADER_SIZE macro in <IOKit/IODataQueueShared.h>.

    This method allocates a new IODataQueue instance and then calls initWithCapacity() with the given size parameter. If the initWithCapacity() fails, the new instance is released and zero is returned.

  • Static method that creates a new IODataQueue instance with the specified number of entries of the given size.

    Declaration

    C++

    static IODataQueue *withEntries( UInt32numEntries, UInt32entrySize);

    Parameters

    numEntries

    Number of entries to allocate space for.

    entrySize

    Size of each entry.

    Return Value

    Reeturns the newly allocated IODataQueue instance. Zero is returned on failure.

    Discussion

    This method will create a new IODataQueue instance with enough capacity for numEntries of entrySize. It does account for the IODataQueueEntry overhead for each entry. Note that the numEntries and entrySize are simply used to determine the data region size. They do not actually restrict the size of number of entries that can be added to the queue.

    This method allocates a new IODataQueue instance and then calls initWithEntries() with the given numEntries and entrySize parameters. If the initWithEntries() fails, the new instance is released and zero is returned.