Remote procedure call functions


Files

file  msg.c
 Message handling functions.

Functions

RTAI_SYSCALL_MODE RT_TASK * rt_rpc (RT_TASK *task, unsigned long to_do, void *result)
  Make a remote procedure call
RTAI_SYSCALL_MODE RT_TASK * rt_rpc_if (RT_TASK *task, unsigned long to_do, void *result)
  Make a remote procedure call, only if the calling task will not be blocked.
RTAI_SYSCALL_MODE RT_TASK * rt_rpc_until (RT_TASK *task, unsigned long to_do, void *result, RTIME time)
  Make a remote procedure call with an absolute timeout.
RTAI_SYSCALL_MODE RT_TASK * rt_rpc_timed (RT_TASK *task, unsigned long to_do, void *result, RTIME delay)
  Make a remote procedure call with a relative timeout.
RTAI_SYSCALL_MODE int rt_isrpc (RT_TASK *task)
  Check if sender waits for reply or not.
RTAI_SYSCALL_MODE RT_TASK * rt_return (RT_TASK *task, unsigned long result)
  Return (sends) the result back to the task that made the related remote procedure call.
RTAI_SYSCALL_MODE RT_TASK * rt_rpcx (RT_TASK *task, void *smsg, void *rmsg, int ssize, int rsize)
  Make an extended remote procedure call
RTAI_SYSCALL_MODE 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.
RTAI_SYSCALL_MODE 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.
RTAI_SYSCALL_MODE 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.
RTAI_SYSCALL_MODE 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.

Function Documentation

RTAI_SYSCALL_MODE int rt_isrpc ( RT_TASK *  task  ) 

Check if sender waits for reply or not.

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. Such an inquiry may be needed when a server task must provide services to both rt_sends (FIXME) and rt_rtcs. No answer is required if the message is sent by an rt_send function or the sender called rt_rpc_timed() or rt_rpc_until() but it is already timed out.

Parameters:
task pointer to a task structure.
Returns:
If the task waits for a return reply, a nonzero value is returned. Otherwise 0 is returned.
Note:
rt_isrpc does not perform any check on pointer task. rt_isrpc cannot figure out what RPC result the sender is waiting for.
rt_return() is intelligent enough to not send an answer to a task which is not waiting for it. Therefore using rt_isrpc might not be necessary.

Definition at line 652 of file msg.c.

References RT_SCHED_RETURN, and task.

RTAI_SYSCALL_MODE RT_TASK* rt_return ( RT_TASK *  task,
unsigned long  result 
)

Return (sends) the result back to the task that made the related remote procedure call.

rt_return sends the result result to the task task. If the task calling rt_rpc is not waiting the answer (i.e. killed or timed out) this return message is silently discarded. The returning task tries to release any previously inheredited priority inherediting the highest priority of any rpcing task still waiting for a return, but only if does not own a resource semaphore. In the latter case it will keep the eighest inheredited priority till it has released the resource ownership and no further message is waiting for a return. That means that in the case priority inheritance is coming only from rpced messages the task will return to its base priority when no further message is queued for a return. Such a scheme automatically sets a dynamic priority ceiling in the case priorities are inheredited both from intertask messaging and resource semaphores ownership.

Returns:
On success, task (the pointer to the task that is got 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:
  • 0: The reply message was not delivered.
  • 0xFFFF: task does not refer to a valid task.
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.
See also: notes under rt_rpc().

Definition at line 693 of file msg.c.

References CHECK_SENDER_MAGIC, cpuid, dequeue_blocked(), flags, RT_SCHED_DELAYED, RT_SCHED_READY, RT_SCHED_RETURN, rt_schedule(), and task.

Here is the call graph for this function:

RTAI_SYSCALL_MODE 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_returns sends the result msg of size size to the task task. If the task calling rt_rpcx is not waiting the answer (i.e. killed or timed out) this return message is silently discarded. The returning task tries to release any previously inheredited priority inherediting the highest priority of any rpcing task still waiting for a return, but only if does not own a resource semaphore. In the latter case it will keep the eighest inheredited priority till it has released the resource ownership and no further message is waiting for a return. That means that in the case priority inheritance is coming only from rpced messages the task will return to its base priority when no further message is queued for a return. Such a scheme automatically sets a dynamic priority ceiling in the case priorities are inheredited both from intertask messaging and resource semaphores ownership.

Returns:
On success, task (the pointer to the task that is got 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:
  • 0: The reply message was not delivered.
  • 0xFFFF: task does not refer to a valid task.
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.
See also: notes under rt_rpcx().

Definition at line 1537 of file msg.c.

References rt_return(), and task.

Here is the call graph for this function:

RTAI_SYSCALL_MODE RT_TASK* rt_rpc ( RT_TASK *  task,
unsigned long  to_do,
void *  result 
)

Make a remote procedure call

rt_rpc makes a Remote Procedure Call (RPC). rt_rpc is used for synchronous inter task messaging as it sends the message msg to the task task and blocks waiting until a return is received from the called task. So the caller task is always blocked and queued up in priority order 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_receive function. It can send an answer with rt_return().

Parameters:
task pointer to a RT_TASK structure.
msg message to send.
reply points to a buffer provided by the caller were the returned result message, any 4 bytes integer, is to be place.
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. On other failure, a special value is returned as described below:
  • 0: the receiver task was killed before receiving the message.
  • 0xFFFF: task does not refer to a valid task.
See also: rt_receive_*, rt_return(), rt_isrpc().

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.
The trio rt_rpc(), rt_receive(), rt_return() implement functions similar to its peers send-receive-replay found in QNX, except that in RTAI only four bytes messages contained in any integer can be exchanged. That's so because it is more efficient and often enough. If you need to pass arbitrarely long messages see the extended intertask messaging functions. Moreover note also that we prefer the idea of calling a function by using a message and then wait for a return value since it is believed to give a better idea of what is meant for synchronous message passing. For a more truly QNX like way of inter task messaging use the support of the upper cased functions: rt_Send-rt_Recieve-rt_Reply.

Definition at line 382 of file msg.c.

References CHECK_SENDER_MAGIC, cpuid, enqueue_blocked(), flags, msg_not_sent, RT_SCHED_DELAYED, RT_SCHED_READY, RT_SCHED_RECEIVE, RT_SCHED_RETURN, RT_SCHED_RPC, and task.

Here is the call graph for this function:

RTAI_SYSCALL_MODE RT_TASK* rt_rpc_if ( RT_TASK *  task,
unsigned long  to_do,
void *  result 
)

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

rt_rpc_if tries to make a Remote Procedure Call (RPC). If the receiver task is ready to accept a message rt_rpc_if sends the message msg then it always block until a return is received. In this case the caller task is blocked and queued up in priority order while the receiver inheredits the blocked sender priority if it is higher (lower in value) than its. 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().

Parameters:
task pointer to a RT_TASK structure.
msg message to send.
reply points to a buffer provided by the caller.
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 safe always.

Definition at line 462 of file msg.c.

References CHECK_SENDER_MAGIC, cpuid, enqueue_blocked(), flags, msg_not_sent, RT_SCHED_DELAYED, RT_SCHED_READY, RT_SCHED_RECEIVE, RT_SCHED_RETURN, and task.

Here is the call graph for this function:

RTAI_SYSCALL_MODE RT_TASK* rt_rpc_timed ( RT_TASK *  task,
unsigned long  to_do,
void *  result,
RTIME  delay 
)

Make a remote procedure call with a relative timeout.

rt_rpc_timed makes a Remote Procedure Call. It sends the message msg to the task task then always waits until a return is received or a timeout occurs. So the caller task is always blocked and queued up in priority order 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_receive() function. It can send the answer with rt_return().

Parameters:
task pointer to a RT_TASK structure.
msg message to send.
reply points to a buffer provided by the caller.
delay is a timeout relative to the current time.
Returns:
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:
  • 0: The message could not be sent or the answer did not arrived in time.
  • 0xFFFF: task does not refer to a valid task.
See also: rt_receive(), rt_return(), rt_isrpc().

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.
See also the notes under rt_rpc().

Definition at line 621 of file msg.c.

References rt_rpc_until(), and task.

Here is the call graph for this function:

RTAI_SYSCALL_MODE RT_TASK* rt_rpc_until ( RT_TASK *  task,
unsigned long  to_do,
void *  result,
RTIME  time 
)

Make a remote procedure call with an absolute timeout.

rt_rpc_until makes a Remote Procedure Call. It sends the message msg to the task task then always waits until a return is received or a timeout occurs. So the caller task is always blocked and queued up in priority order 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_receive() function. It can send the answer with rt_return().

Parameters:
task pointer to a RT_TASK structure.
msg message to send.
reply points to a buffer provided by the caller.
time is an absolute timeout value.
Returns:
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:
  • 0: The message could not be sent or the answer did not arrived in time.
  • 0xFFFF: task does not refer to a valid task.
See also: rt_receive(), rt_return(), rt_isrpc().

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.
See also the notes under rt_rpc().

Definition at line 538 of file msg.c.

References CHECK_SENDER_MAGIC, cpuid, enqueue_blocked(), flags, msg_not_sent, RT_SCHED_DELAYED, RT_SCHED_READY, RT_SCHED_RECEIVE, RT_SCHED_RETURN, RT_SCHED_RPC, and task.

Here is the call graph for this function:

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

Definition at line 1140 of file msg.c.

References rt_rpc(), SET_RPC_MCB, and task.

Here is the call graph for this function:

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

Definition at line 1189 of file msg.c.

References rt_rpc_if(), SET_RPC_MCB, and task.

Here is the call graph for this function:

RTAI_SYSCALL_MODE 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_rpcx_timed makes an extended Remote Procedure Call (RPC). 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 or a timeout occurs. 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.
delay is the relative timeout.
Returns:
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:
  • 0: The message could not be sent or the answer did not arrived in time.
  • 0xFFFF: task does not refer to a valid task.
See also: rt_receive(), rt_return(), rt_isrpc().

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.
See also the notes under rt_rpc().

Definition at line 1297 of file msg.c.

References rt_rpc_timed(), SET_RPC_MCB, and task.

Here is the call graph for this function:

RTAI_SYSCALL_MODE 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_rpcx_until makes an extended Remote Procedure Call (RPC). 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 or a timeout occurs. 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.
time is an absolute timeout value.
Returns:
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:
  • 0: The message could not be sent or the answer did not arrived in time.
  • 0xFFFF: task does not refer to a valid task.
See also: rt_receive(), rt_return(), rt_isrpc().

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.
See also the notes under rt_rpc().

Definition at line 1243 of file msg.c.

References rt_rpc_until(), SET_RPC_MCB, and task.

Here is the call graph for this function:

Generated on Tue Feb 2 17:48:33 2010 for RTAI API by  doxygen 1.4.7