LabVIEW Priority Queue for VxWorks Reference Library

Publish Date: May 06, 2010 | 7 Ratings | 3.29 out of 5 | Print | Submit your review

Overview

This library provides a LabVIEW wrapper for the POSIX priority queue implementation on VxWorks.

Table of Contents

  1. Introduction
  2. Installation
  3. API

1. Introduction

When communicating between processes in a control system, it is often necessary to define which communicated items have the highest priority.  For example, when communicating with tags, we often specify the order that multiple tags are applied so as to allow higher priority tags (such as a safe state or shutdown tag) to override lower priority tags.  However, when sending messages through a queue or RT FIFO, we have limited ability to control the order in which the messages are processed.  We can enqueue an element at the opposite end of a queue, but this limits us to a single high-priority message.  It turns the queue into a stack in the event of multiple high-priority messages, and allows no way to define more than two levels of priority.  When using an RT FIFO we do not have any ability to prioritize elements.

The implementation of VxWorks on LabVIEW RT targets contains a low-level messaging mechanism called a priority queue, defined by the POSIX standard.  You can find more information about the available functions here.  However, these functions use complex data types and are therefore difficult to call directly from LabVIEW.   This library provides an intermediate .out file which provides a LabVIEW-friendly interface to the POSIX priority queue as well as a LabVIEW API for interacting with the .out file.

A priority queue allows you to specify a numeric priority for each message at the time that the message is written into the queue.  When reading the queue, elements of higher priority will be read before elements of lower priority.  Elements of equal priority will be read in a first-in, first-out order.  Therefore, if all elements have the same priority, a priority queue operates much like a regular queue or RT FIFO.

Back to Top

2. Installation

The attached zip contains an installer which will install all necessary files on your development computer.  It is recommended that you use the installer rather than installing the files manually in order to correctly install the RT target support.

Once you have installed the library on your development computer, you must install the LVRT portion of the library on your target.  Use Measurement and Automation explorer to do a custom install of the RT target software and select the LabVIEW Priority Queue for VxWorks component to install.  Note that this library only supports VxWorks targets.  It was tested on a cRIO-9074.

Back to Top

3. API

The following describes the functions provided with this library.

LVPQ Open

This VI creates a priority queue or opens a reference to an existing priority queue.

 

Queue Name

Specifies a name for the queue.  This is required, as queues must have unique names, but is primarily used if you want to connect to the queue using future calls to LVPQ Open.  Note that like ordinary LabVIEW queues, the LVPQ reference can be branched safely, therefore it is not necessary to call LVPQ Open multiple times unless you cannot pass the reference or unless you want to assign difference access types to each reference.

Access Type

Specifies whether this particular reference to the queue is read-only, write-only, or bidirectional.  Specifying a queue reference as read-only or write-only provides error checking for your implementation.  Attempting to write to a read-only queue or read a write-only queue will return error 537559.

Create Queue?

Specifies whether to create a new queue or search for an existing queue matching the Queue Name input.  Attempts to create two queues with the same name will result in error 537551.

Sizes

A cluster specifying the number of messages in the queue as well as the size of each message.

Message Size

Specifies the size, in bytes, of each message in the queue.  Messages must be strings of this length.

Queue Size

Specifies the number of messages in the queue.

LVPQ Reference

This provides a reference to the queue, which is required by the other VIs in this API.  Note that you can create multiple references to the same queue by calling this function with Create Queue? set to false.

error in/error out

Provides standard LabVIEW error functionality.

This VI can return the following error codes:

537550

Invalid options - attempt to create a priority queue reference that is neither a writer nor a reader.

537551

The priority queue with the specified name already exists. If you are attempting to connect to an existing priority queue, set the Create Queue option to false.

537552

The specified priority queue does not exist. If you are attempting to create a new priority queue, set the Create Queue option to True. If you are attempting to destroy a priority queue, it may have been previously destroyed.

537553

Insufficient space to create a new message queue. This may be due to a memory limitation or a limit on the number of queues in the system.

537554

An unknown error occurred while creating a priority queue reference.

537555

Invalid attributes for new priority queue. This is most likely due to an invalid queue or message size.

Other

Any errors returned by a Call Library Function primitive.

LVPQ Write

This VI enqueues an element into the priority queue.

LVPQ Reference In/Out

You can create this reference using LVPQ Open.

Message

A string containing the message to be sent.  This string can be in ASCII representation, or can be a buffer containing other types that have been flattened to string.  In either case, it must match the size specified in the LVPQ Open function.  Unlike RT FIFOs and ordinary queues, this library supports only string data types, you are responsible for flatting any other data type to a string before writing, unflattening it after reading, and adjusting the string size as necessary.

Message Priority

Specifies a priority for the message.  Messages with a higher value for this input will be read out of the queue before messages with a lower value for this input.  The maximum priority is 31, attempting to use a higher priority will result in error 537557 (Unknown error).

Queue Full?

Returns TRUE if there is not space in the queue for the current write operation.  The element is not placed on a full queue and the caller is responsible for responding accordingly (for example, storing the element locally).

error in/error out

Provides standard LabVIEW error functionality.

This VI can return the following error codes:

537557

An unknown error occurred while writing to a priority queue.

537559

Invalid priority queue reference or invalid access type.
Potential causes:
Reference has been closed or lost
Reading a write-only queue
Writing a read-only queue

537561

Message string length must match the size defined at queue creation.

Other

Any errors returned by a Call Library Function primitive.

LVPQ Read

This VI dequeues an element from the priority queue.  This VI does not block, so you must use the Queue Empty? output to poll for new elements.

LVPQ Reference In/Out

You can create this reference using LVPQ Open.

Message

Returns a message that was previously written to the priority queue.  This string can be in ASCII representation, or can be a buffer containing other types that have been flattened to string.

Message Priority

Returns the priority of the read message.  This ranges from 0 to 31.

Queue Full?

Returns TRUE if there are no elements in the queue.  Message and Message Priority are undefined if the queue is empty and therefore you should check this whenever reading elements.

error in/error out

Provides standard LabVIEW error functionality.

This VI can return the following error codes:

537556

An unknown error occurred while reading from a priority queue.

537559

Invalid priority queue reference or invalid access type.
Potential causes:
Reference has been closed or lost
Reading a write-only queue
Writing a read-only queue

Other

Any errors returned by a Call Library Function primitive.

LVPQ Close

This VI closes a reference to a priority queue.

LVPQ Reference In

You can create this reference using LVPQ Open.

Destroy?

Determines whether to release the queue as a whole or only the current reference.  You should generally close all references to a priority queue and destroy it while closing the last reference.  Accessing the reference of a destroyed queue will result in error 537559.

error in/error out

Provides standard LabVIEW error functionality.

This VI can return the following error codes:

537552

The specified priority queue does not exist. If you are attempting to create a new priority queue, set the Create Queue option to True. If you are attempting to destroy a priority queue, it may have been previously destroyed.

537558

An unknown error occured while closing a priority queue reference.

Other

Any errors returned by a Call Library Function primitive.

LVPQ Info

This VI returns information about a priority queue reference.

LVPQ Reference In/Out

You can create this reference using LVPQ Open.

Current Items

Returns the number of items currently waiting to be read.

Access Type

Returns the access type of the reference, as specified in LVPQ Open call that created this reference.

Sizes

Returns the sizes of the queue, as specified in the LVPQ Open call that created the queue.

error in/error out

Provides standard LabVIEW error functionality.

This VI can return the following error codes:

537559

Invalid priority queue reference or invalid access type.
Potential causes:
Reference has been closed or lost
Reading a write-only queue
Writing a read-only queue

537560

An unknown error occurred while checking the attributes of a priority queue.

Other

Any errors returned by a Call Library Function primitive.

Back to Top

Bookmark & Share


Downloads

Attachments:

lvpq_1_0_0.zip

Requirements


Ratings

Rate this document

Answered Your Question?
Yes No

Submit