Mac Developer Library

Developer

IOSharedDataQueue Class Reference

Options
Deployment Target:

On This Page
Language:

IOSharedDataQueue

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

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable @import Kernel;

Availability


Available in OS X v10.5 and later.
  • Dequeues the next available entry on the queue and copies it into the given data pointer.

    Declaration

    C++

    virtual Boolean dequeue( void *data, UInt32 *dataSize);

    Parameters

    data

    A pointer to the data memory region in which to copy the next entry data on the queue. If this parameter is 0 (NULL), it will simply move to the next entry.

    dataSize

    A pointer to the size of the data parameter. On return, this contains the size of the actual entry data - even if the original size was not large enough.

    Return Value

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

    Discussion

    This function will dequeue the next available entry on the queue. If a data pointer is provided, it will copy the data into the memory region if there is enough space available as specified in the dataSize parameter. If no data pointer is provided, it will simply move the head value past the current entry.

    Import Statement

  • 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.

    Import Statement

  • Initializes an IOSharedDataQueue 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 and DATA_QUEUE_MEMORY_APPENDIX_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>.

    Import Statement

  • Used to peek at the next entry on the queue.

    Declaration

    C++

    virtual IODataQueueEntry * peek();

    Return Value

    Returns a pointer to the next IODataQueueEntry if one is available. 0 (NULL) is returned if the queue is empty.

    Discussion

    This function can be used to look at the next entry which allows the entry to be received without having to copy it with dequeue. In order to do this, call peek to get the entry. Then call dequeue with a NULL data pointer. That will cause the head to be moved to the next entry, but no memory to be copied.

    Import Statement

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

    Declaration

    C++

    static IOSharedDataQueue *withCapacity( UInt32size);

    Parameters

    size

    The size of the data queue memory region.

    Return Value

    Returns the newly allocated IOSharedDataQueue 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.

    Import Statement

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

    Declaration

    C++

    static IOSharedDataQueue *withEntries( UInt32numEntries, UInt32entrySize);

    Parameters

    numEntries

    Number of entries to allocate space for.

    entrySize

    Size of each entry.

    Return Value

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

    Discussion

    This method will create a new IOSharedDataQueue 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.

    Import Statement

Instance Variables

  • Reserved for future use. (Internal use only)

    Declaration

    C++

    ExpansionData * _reserved;

  • Reserved for future use. (Internal use only)

    Declaration

    C++

    ExpansionData * _reserved;