# msg.c File Reference

## Detailed Description

Message handling functions.

Author:
  Paolo Mantegazza

Note:
  Copyright (C) 1999-2003 Paolo Mantegazza <mantegazza@aero.polimi.it> [ Specific COPYRIGHTS follow along the code ]

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Include dependency graph for msg.c:

## Functions

RT_TASK * | rt_send (RT_TASK *task, unsigned int msg)
| Send a message.
RT_TASK * | rt_send_if (RT_TASK *task, unsigned int msg)
| Send a message, only if the calling task will not be blocked.
RT_TASK * | rt_send_until (RT_TASK *task, unsigned int msg, RTIME time)
RT_TASK * | rt_send_timed (RT_TASK *task, unsigned int msg, RTIME delay)
RT_TASK * | rt_rpc (RT_TASK *task, unsigned int to_do, unsigned int *result)
| Make a remote procedure call.
RT_TASK * | rt_rpc_if (RT_TASK *task, unsigned int to_do, unsigned int *result)
| Make a remote procedure call, only if the calling task will not be blocked.
RT_TASK * | rt_rpc_until (RT_TASK *task, unsigned int to_do, unsigned int *result, RTIME time)
| Make a remote procedure call with an absolute timeout.
RT_TASK * | rt_rpc_timed (RT_TASK *task, unsigned int to_do, unsigned int *result, RTIME delay)
| Make a remote procedure call with a relative timeout.
int | rt_isrpc (RT_TASK *task)
| Check if sender waits for reply or not.
RT_TASK * | rt_return (RT_TASK *task, unsigned int result)
| Return (sends) the result back to the task that made the related remote procedure call.
RT_TASK * | rt_evdrp (RT_TASK *task, unsigned int *msg)
| Eavedrop (spy) the content of a message.
RT_TASK * | rt_receive (RT_TASK *task, unsigned int *msg)
| Receive a message.
RT_TASK * | rt_receive_if (RT_TASK *task, unsigned int *msg)
| Receive a message, only if the calling task is not blocked.
RT_TASK * | rt_receive_until (RT_TASK *task, unsigned int *msg, RTIME time)
| Receive a message with an absolute timeout.
RT_TASK * | rt_receive_timed (RT_TASK *task, unsigned int *msg, RTIME delay)
| Receive a message with a relative timeout.
RT_TASK * | rt_rpcx (RT_TASK *task, void *smsg, void *rmsg, int ssize, int rsize)
| Make an extended remote procedure call.
RT_TASK * | rt_rpcx_if (RT_TASK *task, void *smsg, void *rmsg, int ssize, int rsize)
| Make an extended remote procedure call, only if the calling task will not be blocked.
RT_TASK * | rt_rpcx_until (RT_TASK *task, void *smsg, void *rmsg, int ssize, int rsize, RTIME time)
| Make an extended remote procedure call with absolute timeout.
RT_TASK * | rt_rpcx_timed (RT_TASK *task, void *smsg, void *rmsg, int ssize, int rsize, RTIME delay)
| Make an extended remote procedure call with a relative timeout.
RT_TASK * | rt_sendx (RT_TASK *task, void *msg, int size)
| Send an extended message.
RT_TASK * | rt_sendx_if (RT_TASK *task, void *msg, int size)
| Send an extended message, only if the calling task will not be blocked.
RT_TASK * | rt_sendx_until (RT_TASK *task, void *msg, int size, RTIME time)
| Send an extended message with absolute timeout.
RT_TASK * | rt_sendx_timed (RT_TASK *task, void *msg, int size, RTIME delay)
| Send an extended message with relative timeout.
RT_TASK * | rt_returnx (RT_TASK *task, void *msg, int size)
| Return (sends) an extended result back to the task that made the related extended remote procedure call.
RT_TASK * | rt_evdrpx (RT_TASK *task, void *msg, int size, int *len)
| Eavedrop (spy) the content of an extended message.
RT_TASK * | rt_receivex (RT_TASK *task, void *msg, int size, int *len)
| Receive an extended message.
RT_TASK * | rt_receivex_if (RT_TASK *task, void *msg, int size, int *len)
| Receive an extended message, only if the calling task is not blocked.
RT_TASK * | rt_receivex_until (RT_TASK *task, void *msg, int size, int *len, RTIME time)
| Receive an extended message with an absolute timeout.
RT_TASK * | rt_receivex_timed (RT_TASK *task, void *msg, int size, int *len, RTIME delay)
| Receive an extended message with a relative timeout.

## Function Documentation

RT_TASK* rt_rpcx | ( | RT_TASK * | task,
|  | void * | smsg,
|  | void * | rmsg,
|  | int | ssize,
|  | int | rsize
| ) |

Make an extended remote procedure call.

rt_rpcx makes an extended Remote Procedure Call (RPC). rt_rpcx is used for synchronous inter task messaging. It sends an arbitrary smsg of size ssize bytes to the task task then it always blocks waiting until a message, of size rsize bytes at most, is returned in rmsg from the called task. If the returned message is greater tha rsize it will be truncated. So the caller task is always blocked on the receiver priority queue while the receiver inheredits the blocked sender priority if it is higher (lower in value) than its. The receiver task may get the message with any rt_receivex function. It can send an answer with rt_returnx().

Parameters:

  | task | pointer to the RT_TASK structure of the receiver.
  | smsg | points to the message to be sent.
  | rmsg | points to the message to be returned by the receiver.
  | ssize | size of the message to be sent.
  | rsize | maximum allowed size for the message to be received.

Returns:
  On success, task (the pointer to the task that received the message) is returned. If the message has not been sent (e.g. the task task was killed before receiving the message) 0 is returned.

See also: rt_receivex_*, rt_returnx(), rt_isrpc().

Note:
  The trio rt_rpcx(), rt_receivex(), rt_returnx() implements functions similar to its peers send-receive-reply found in QNX. For a even greater compatibility see rt_Send-rt_Receive-rt_Reply.

RT_TASK* rt_rpcx_if | ( | RT_TASK * | task,
|  | void * | smsg,
|  | void * | rmsg,
|  | int | ssize,
|  | int | rsize
| ) |

Make an extended remote procedure call, only if the calling task will not be blocked.

rt_rpcx_if tries to make an extended Remote Procedure Call (RPC). If the receiver task is ready to accept a message rt_rpcx_if sends the message as it will be done by rt_rpcx. If the receiver is not ready rt_rpcx_if returns immediately. The receiver task may get the message with any rt_receivex function. It can send the answer with * rt_returnx().

Parameters:

  | task | pointer to the RT_TASK structure of the receiver.
  | smsg | points to the message to be sent.
  | rmsg | points to the message to be returned by the receiver.
  | ssize | size of the message to be sent.
  | rsize | maximum allowed size for the message to be received.

Returns:
  On success, task (the pointer to the task that received the message) is returned. If message has not been sent, 0 is returned. On other failure, a special value is returned as described below:
  - 0: The task task was not ready to receive the message or it was killed before sending the reply.
  - 0xFFFF: task does not refer to a valid task.

See also: notes under rt_rpc().

Note:
  Since all the messaging functions return a task address, 0xFFFF could seem an inappropriate return value. However on all the CPUs RTAI runs on, 0xFFFF is not an address that can be used by any RTAI task, so it is should be always safe.