Client API Documentation

This document describes the client API for making remote procedure calls to hosts. For a detailed explanation of how responses work and the overall message flow, see the Networking Architecture document.

Overview

The client API provides methods for making remote procedure calls (RPC) to hosts. There are two main modes of operation:

1. Synchronous: Blocks while waiting for a response
2. Asynchronous: Sends request and receives response later via a queue

Response Handling

Understanding Responses

All responses from hosts follow the same structure:

Synchronous Response Flow

When making synchronous calls using remoteCall(), the flow is:

1. Client sends request to host
2. Host sends "ack" acknowledgment
3. Client blocks and waits for response
4. Host processes request and sends response
5. Client receives response and unblocks

Example:

Asynchronous Response Flow

For asynchronous operations, you must set up a receiver thread before making async calls:

1. Write programm which makes async calls using remoteCallAsync() and gets answers via getFromQueue()
2. Create the Reciever Thread
3. Start both via parallel.waitForAll()
4. Host processes request and sends response to the async protocol
5. Receiver thread enqueues the response
6. Poll the queue to get responses when ready

Example:

Timeout Management

• Set appropriate timeouts based on expected response time
• Handle timeout errors gracefully
• Consider using async calls for long-running operations

Complete Workflow Examples

Synchronous RPC Workflow

Asynchronous RPC Workflow with Multiple Requests

Broadcast and Pick One Pattern

Constructor

Client(networkMask)

Creates a new client instance.

Parameters:

• networkMask (string, optional): Prefix for protocol names. Defaults to empty string.

Returns:

• client (table): Client instance with the following methods:

Properties:

• directProtocol (string): Protocol for direct communication
• networkMask (string): Network mask used
• receiveProtocol (string): Protocol for receiving responses
• receiveProtocolAsync (string): Protocol for async responses

Methods

receive(protocol, timeout)

Receives messages from the network.

Parameters:

• protocol (string): Protocol to listen on
• timeout (number): Maximum time to wait in seconds

Returns:

• state (boolean): Success/failure indicator
• result (various): Result data or error message
• sid (number): Sender ID (if successful)

remoteCallAsync(methodName, params, receiverId, protocol, receiveProtocol)

Asynchronously calls a remote method.

Parameters:

• methodName (string): Name of the method to call
• params (table): Parameters to pass to the method
• receiverId (number): ID of the host to call
• protocol (string, optional): Protocol to use
• receiveProtocol (string, optional): Protocol for responses

Returns:

• state (boolean): Success/failure indicator
• result (string): "ack" if acknowledged, or error message

remoteCall(protocol, receiverId, methodName, params, timeout)

Synchronously calls a remote method.

Parameters:

• protocol (string): Protocol to use
• receiverId (number): ID of the host to call
• methodName (string): Name of the method to call
• params (table): Parameters to pass to the method
• timeout (number, optional): Timeout in seconds. Defaults to 0 (infinite)

Returns:

• state (boolean): Success/failure indicator
• result (various): Method result or error message

getReceiverThread(maxSize)

Gets a thread function for receiving async messages.

Parameters:

• maxSize (number, optional): Maximum queue size. Defaults to 100

Returns:

• receiverThread (function): Thread function that processes incoming messages

getFromQueue()

Retrieves messages from the queue.

Returns:

• state (boolean): Success/failure indicator
• result (various): Message data or error message
• sid (number): Sender ID

broadcast(methodName, params, protocol, timeout)

Broadcasts a message to all hosts.

Parameters:

• methodName (string): Name of the method to call
• params (table): Parameters to pass
• protocol (string, optional): Protocol to use
• timeout (number): Maximum time to wait for responses

Returns:

• responses (table): Array of responses from hosts
  • Each response contains:
    • message (various): Response message
    • senderId (number): ID of responding host

broadcastAsync(methodName, params, protocol, receiveProtocol)

Asynchronously broadcasts a message.

Parameters:

• methodName (string): Name of the method to call
• params (table): Parameters to pass
• protocol (string, optional): Protocol to use
• receiveProtocol (string, optional): Protocol for responses

pickOneAndRemoteCallAsync(protocol, methodName, params, receiveProtocol)

Selects one host and calls a method asynchronously.

Parameters:

• protocol (string): Protocol to use
• methodName (string): Name of the method to call
• params (table): Parameters to pass
• receiveProtocol (string, optional): Protocol for responses

Returns:

• state (boolean): Success/failure indicator
• receiverId (number): ID of the selected host (if successful)

pickOneAndRemoteCall(protocol, methodName, params, timeout)

Selects one host and calls a method synchronously.

Parameters:

• protocol (string): Protocol to use
• methodName (string): Name of the method to call
• params (table): Parameters to pass
• timeout (number, optional): Timeout in seconds. Defaults to 0

Returns:

• state (boolean): Success/failure indicator
• result (various): Method result or error message
• receiverId (number): ID of the selected host (if successful)

pickOneAndRemoteCallRetry(methodName, params, protocol, sleepTime)

Retries picking a host and calling a method until successful.

Parameters:

• methodName (string): Name of the method to call
• params (table): Parameters to pass
• protocol (string): Protocol to use
• sleepTime (number, optional): Sleep time between retries. Defaults to 120

Returns:

• state (boolean): Success indicator
• result (various): Method result