|
消息函数
作者 Ray
RTEMS版权所有，转载请注明来源www.rtems.net，作者Ray
14.4: 函数
14.4.1 : MESSAGE_QUEUE_CREATE- 创建一个队列
函数原型:
rtems_status_code rtems_message_queue_create(
rtems_name name,
rtems_unsigned32 count,
rtems_unsigned32 max_message_size,
rtems_attribute attribute_set,
rtems_id *id
);
返回值代表的状态:
RTEMS_SUCCESSFUL- 成功地创建消息队列
RTEMS_INVALID_NAME- 无效任务名字
RTEMS_INVALID_ADDRESS- ID标识是空值
RTEMS_INVALID_NUMBER- 无效的coun值
RTEMS_INVALID_SIZE- 无效的消息大小max_message_size
RTEMS_TOO_MANY- 已经创建了太多队列
RTEMS_UNSATISFIED- 不能分配消息缓存
RTEMS_MP_NOT_CONFIGURED- 没有配置的多重处理（用于全局消息创建）
RTEMS_TOO_MANY- 已经有太多的全局对象
描述:
该函数在本地节点上创建一个用户命名的消息队列。为了控制和维护队列，RTEMS为队列分配了QCB 。同时为信息分配了内存空间，队列长度使用count初始化，max_message_size初始化消息的对大长度。*id是函数返回的ID标识。
attribute_set设置了RTEMS_PRIORITY，那么等候消息的任务按照任务优先级排序。设置了RTEMS_FIFO时，队列按照FIFO排序。
注意:
除非是远端节点需要和消息队列交互，否则消息队列将会是本地的。这样可以减少系统开销。如果创建了全局的的消息队列，那么消息的名称和ID会被传输到系统中每个节点的全局对象表中。
对于全局消息队列，最大的消息长度在MPCI中定义。
全局对象的总数，包括消息队列，被 配置表中maximum_global_objects字段限制。
14.4.2 : MESSAGE_QUEUE_IDENT-获取消息队列的 ID标识
函数原型:
rtems_status_code rtems_message_queue_ident(
rtems_name name,
rtems_unsigned32 node,
rtems_id *id
);
返回值代表的状态:
RTEMS_SUCCESSFUL- 成功地获得队列ID
RTEMS_INVALID_ADDRESS- ID标识是空值
RTEMS_INVALID_NAME- 找不到对应名字的消息队列
RTEMS_INVALID_NODE- 无效的结点ID
描述:
该函数根据消息队列名称查找消息队列。如果名字不唯一，就返回找到的第一个队列ID。
注意:
如果node是RTEMS_SEARCH_ALL_NODES，将首先搜索本地节点，然后按照节点编号，搜索所有的结点。
如果node编号是一个有效的远端节点，并不会真正的在远端节点上进行搜索，只会搜索本地节点中的全局区域。
14.4.3 : MESSAGE_QUEUE_DELETE- 删除一个消息队列
函数原型:
rtems_status_code rtems_message_queue_delete(
rtems_id id
);
返回值代表的状态:
RTEMS_SUCCESSFUL- 队列删除成功
RTEMS_INVALID_ID- 无效的队列 ID标识
RTEMS_ILLEGAL_ON_REMOTE_OBJECT- 不能够删除远端的队列
描述:
该函数删除ID标识指定的消息队列。该函数将解除所有消息队列上的阻塞任务的阻塞状态，并且返回一个表明队列被删除的状态码。如果没有任务等候，但是队列包含消息，那么函数将丢弃这些消息并且释放内存。此外QCB也会被释放。
注意:
如果调用者允许抢占，而且队列删除后有高优先级的任务就绪，那么会发生抢占。当然，如果高优先的任务不是本地任务，不会发生抢占。
删除的调用者不一定是队列的创建者，只要是知道队列ID的本地任务就可以了。
用来代表远端任务的代理在消息队列被删除时也会被释放。
14.4.4 : MESSAGE_QUEUE_SEND 在消息队列的后面添加消息
函数原型:
rtems_status_code rtems_message_queue_send(
rtems_id id,
void *buffer,
rtems_unsigned32 size
);
返回值代表的状态:
RTEMS_SUCCESSFUL- 消息成功地送出
RTEMS_INVALID_ID- 无效的队列 ID 标识
RTEMS_INVALID_SIZE- 无效的消息 size 大小
RTEMS_INVALID_ADDRESS- buffer 是空值
RTEMS_UNSATISFIED- 消息超过了 buffer 容量
RTEMS_TOO_MANY- 已经到达队列的存储界限
描述 :
该函数向 ID 标识指定的队列发送消息 ， 消息体在 buffer 中定义 ， 消息长度用 size 定义。如果有任务正在队列等候消息，那么该消息会被传递各该任务，并且解除任务阻塞。如果没有任务在队列中等候,那么消息会存放在队列的缓存器后端。
注意:
如果调用者支持抢占，那么他有可能被解除阻塞的任务抢占。
向远端节点传送消息会对远端结点产生一个发送消息的请求。
如果等待消息的任务不是本地任务，那么消息将会传递给对应的节点。然后释放任务的代理。
14.4.5 : MESSAGE_QUEUE_URGENT 将消息放在一个队列的前面
函数原型:
rtems_status_code rtems_message_queue_urgent(
rtems_id id,
void *buffer,
rtems_unsigned32 size
);
返回值代表的状态:
RTEMS_SUCCESSFUL- 消息成功地送出
RTEMS_INVALID_ID- 无效的队列 ID 标识
RTEMS_INVALID_SIZE- 无效的消息 size 大小
RTEMS_INVALID_ADDRESS- buffer 是空值
RTEMS_UNSATISFIED- 消息超过了 buffer 容量
RTEMS_TOO_MANY- 已经到达队列的存储界限
描述 :
该函数向 ID 标识指定的队列发送消息 ， 消息体在 buffer 中定义 ， 消息长度用 size 定义。如果有任务正在队列等候消息，那么该消息会被传递各该任务，并且解除任务阻塞。如果没有任务在队列中等候,那么消息会存放在队列的缓存器前端。
注意:
如果调用者支持抢占，那么他有可能被解除阻塞的任务抢占。
向远端节点传送消息会对远端结点产生一个发送消息的请求。
如果等待消息的任务不是本地任务，那么消息将会传递给对应的节点。然后释放任务的代理。
14.4.6 : MESSAGE_QUEUE_BROADCAST- 向消息队列广播消息
函数原型:
rtems_status_code rtems_message_queue_broadcast(
rtems_id id,
void *buffer,
rtems_unsigned32 size,
rtems_unsigned32 *count
);
返回值代表的状态:
RTEMS_SUCCESSFUL- 消息成功地送出
RTEMS_INVALID_ID- 无效的队列 ID 标识
RTEMS_INVALID_SIZE- 无效的消息 size 大小
RTEMS_INVALID_ADDRESS- buffer 是空值
RTEMS_UNSATISFIED- 消息超过了 buffer 容量
描述 :
该函数向消息队列上面所有等待的任务发送消息。count返回了接收到消息的任务数目。
注意:
如果调用者支持抢占，那么他有可能被解除阻塞的任务抢占。
函数的执行效率和等待的任务数目有关，但是在任务数目相同的情况下，它比 rtems_message_queue_send
效率高。
向远端节点广播消息会对远端结点产生一个发送广播消息的请求。
如果接收到广播消息的任务不是本地任务，那么消息将会传递给对应的节点。然后释放任务的代理。
14.4.7 : MESSAGE_QUEUE_RECEIVE-接受来自一个队列的消息
函数原型:
rtems_status_code rtems_message_queue_receive(
rtems_id id,
void *buffer,
rtems_unsigned32 *size,
rtems_unsigned32 option_set,
rtems_interval timeout
);
返回值代表的状态:
RTEMS_SUCCESSFUL- 成功地收到消息
RTEMS_INVALID_ID- 无效的队列 ID 标识
RTEMS_INVALID_ADDRESS- 缓冲 buffer 是空值
RTEMS_INVALID_ADDRESS- 计数 count 是空值
RTEMS_UNSATISFIED- 队列是空的
RTEMS_TIMEOUT- 等候消息时使用定时
RTEMS_OBJECT_WAS_DELETED- 当等候的时候 ， 队列被删除
描述:
该函数接受ID标识指定消息队列中一个消息。 option_set中RTEMS_WAIT和RTEMS_NO_WAIT选项告定义了函数未接收到消息时是否立即返回。如果队列中有消息，函数将消息复印到buffer，消息大小使用size返回。
如果使用RTEMS_NO_WAIT要求任务立刻返回，并且队列是空的，那么返回RTEMS_UNSATISFIED表明没有取得需要的消息。如果任务需要等待消息，那么将会按照FIFO（RTEMS_FIFO）或者优先级（RTEMS_PRIORITY
）方式排序等待消息。一个指出这一个条件被退还的状态 [代]码。
一个选择在队列等候的任务也可以使用定时器来等待一定的时间。如果定时器设置为RTEMS_NO_TIMEOUT，那么任务将会循环等候。
注意:
如果从远程的消息队列上获取消息，那么会传递给对应的节点消息获取信息。如果远程队列中没有需要的消息，而同时任务需要等待该消息，就会在远端节点上创建代理，直到获取消息才会删除代理。如果需要定时服务，必须要有时钟支持。
14.4.8 : MESSAGE_QUEUE_GET_NUMBER_PENDING- 在指定队列上获取消息个数
函数原型:
rtems_status_code rtems_message_queue_get_number_pending(
rtems_id id,
rtems_unsigned32 *count
);
返回值代表的状态:
RTEMS_SUCCESSFUL- 成功获得多个消息
RTEMS_INVALID_ADDRESS- 计数count是空值
RTEMS_INVALID_ID- 无效队列ID标识
描述:
函数获取消息队列上的消息个数，如果队列为空，*count为0
注意:
如果消息队列是远端节点上的全局队列，那么需要向远端节点发送获取消息数目的请求。
14.4.9 : MESSAGE_QUEUE_FLUSH- 清除消息队列上的所有消息
函数原型:
rtems_status_code rtems_message_queue_flush(
rtems_id id,
rtems_unsigned32 *count
);
返回值代表的状态:
RTEMS_SUCCESSFUL- 成功地情况消息队列
RTEMS_INVALID_ADDRESS- 计数count是空值
RTEMS_INVALID_ID- 无效的队列 ID标识
描述:
该函数移除消息队列中所有的消息。count返回了被删除消息的数目。如果消息队列为空，那么*count是0。
注意:
如果消息队列是远端节点上的全局队列，那么需要向远端节点发送清空消息队列的请求。
|
