RTAI API --- RPC functions

rt_rpc 
rt_rpc_if 
rt_rpc_until 
rt_rpc_timed 
rt_isrpc 

rt_return

please refer to: https://www.rtai.org/userfiles/documentation/magma/html/api

****************************************************************************************************************************************************************************

NAME

rt_rpc - make a remote procedure call

SYNOPSIS
#include "rtai_sched.h"
RT_TASK *rt_rpc (RT_TASK *task, unsigned int msg, unsigned int *reply);

DESCRIPTION
rt_rpc makes a Remote Procedure Call. RPC is like a send/receive pair. rt_rpc sends the message msg to the task task then waits until a reply is received. The caller task is always blocked and queued up. (Queueing may happen in priority order or on FIFO base. This is determined by compile time option MSG_PRIORD.) 
The receiver task may get the message with any rt_receive_* function. It can send the answer with rt_return. 
reply points to a buffer provided by the caller.

RETURN VALUE

On success, task (the pointer to the task that received the message) is returned. If message has not been sent (e.g. the task task was killed before receiving the message) 0 is returned. On other failure, a special value is returned as described below.
ERRORS
0
The receiver task was killed before receiving the message.
0xffff
task does not refer to a valid task.

BUGS
There is no guarantee, that the value of pointer task differs from 0xffff. In this theoretical case the caller cannot figure out if the operation was succesful or not.

SEE ALSO
rt_receive_*, rt_return, rt_isrpc.
*****************************************************************************************************************************************************
NAME

rt_rpc_if - make a remote procedure call if receiver is ready

SYNOPSIS

#include "rtai_sched.h"
RT_TASK *rt_rpc_if (RT_TASK *task, unsigned int msg, unsigned int *reply);

DESCRIPTION
rt_rpc_if tries to make a Remote Procedure Call. If the receiver task is ready to accept a message rt_rpc_if sends the message msg then waits until a reply is received. In this case the caller task is blocked and queued up. (Queueing may happen in priority order or on FIFO base. This is determined by compile time option MSG_PRIORD.) If the receiver is not ready rt_rpc_if returns immediately. 
The receiver task may get the message with any rt_receive_* function. It can send the answer with rt_return. 
reply points to a buffer provided by the caller.

RETURN VALUE
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.
ERRORS
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.
BUGS

There is no guarantee, that the value of pointer task differs from 0xffff. In this theoretical case the caller cannot figure out if the operation was succesful or not.
SEE ALSO
rt_receive_*, rt_return, rt_isrpc.
********************************************************************************************************************************************************

NAME
rt_rpc_until, rt_rpc_timed - make a remote procedure call with timeout

SYNOPSIS
#include "rtai_sched.h"
RT_TASK *rt_rpc_until (RT_TASK *task, unsigned int msg, unsigned int *reply, RTIME time);

RT_TASK *rt_rpc_timed (RT_TASK *task, unsigned int msg, unsigned int *reply, RTIME delay);

DESCRIPTION
rt_rpc_until and rt_rpc_timed make a Remote Procedure Call. They send the message msg to the task task then wait until a reply is received or a timeout occurs. The caller task is always blocked and queued up. (Queueing may happen in priority order or on FIFO base. This is determined by compile time option MSG_PRIORD.) 
The receiver task may get the message with any rt_receive_* function. It can send the answer with rt_return. 
reply points to a buffer provided by the caller. 
time is an absolute value. delay is relative to the current time.

RETURN VALUE
On success, task (the pointer to the task that received the message) is returned. If message has not been sent or no answer arrived, 0 is returned. On other failure, a special value is returned as described below.
ERRORS
0
The message could not be sent or the answer did not arrived in time.
0xffff
task does not refer to a valid task.
BUGS

There is no guarantee, that the value of pointer task differs from 0xffff. In this theoretical case the caller cannot figure out if the operation was succesful or not.
SEE ALSO

rt_receive_*, rt_return, rt_isrpc.
***********************************************************************************************************************************************************************************

NAME

rt_isrpc - check if sender waits for reply or not
SYNOPSIS

#include "rtai_sched.h"
int rt_isrpc (RT_TASK *task);

DESCRIPTION
After receiving a message, by calling rt_isrpc a task can figure out whether the sender task task is waiting for a reply or not.
No answer is required if the message sent by a rt_send_* function or the sender called rt_rpc_timed or rt_rpc_until but it is already timed out.
RETURN VALUE

If the task waits for a reply, a nonzero value is returned. Otherwise 0 is returned.

BUGS
rt_isrpc does not perform any check on pointer task. 
rt_isrpc cannot figure out what RPC result the sender is waiting for.
COMMENTS

rt_return is intelligent enough to not send an answer to a task which is not waiting for it. Therefore using rt_isrpc is not necessary and discouraged.
**********************************************************************************************************************************************************************************
NAME

rt_return - send back the result of a remote procedure call
SYNOPSIS

#include "rtai_sched.h"
RT_TASK *rt_return (RT_TASK *task, unsigned int result);

DESCRIPTION
rt_result sends the result result to the task task. If the task calling rt_rpc* previously is not waiting the answer (i.e. killed or timed out) this return message is silently discarded.

RETURN VALUE
On success, task (the pointer to the task that is got the the reply) is returned. If the reply message has not been sent, 0 is returned. On other failure, a special value is returned as described below.
ERRORS
0
The reply message was not delivered.
0xffff
task does not refer to a valid task.
BUGS

There is no guarantee, that the value of pointer task differs from 0xffff. In this theoretical case the caller cannot figure out if the operation was succesful or not.