Server/Client I/O

Often you will want to call one model from another like a functions. This would required sending the input variable(s) to the model being called and then sending the output variables(s) back to the calling model. We refer to this as a Remote Procedure Call (RPC). The model being called can be considered a server providing its calculations as a service to the client (the calling model). The yggdrasil provides options for treating models as server and clients.

One Server, One Client

In the example below, the “server” model computes the nth number in the Fibonacci sequence and the “client” model calls the server to get a certain portion of the Fibonacci sequences and then writes it to a log. The server will continue processing requests until all clients connected to it have disconnected.

Model Code:

import numpy as np
from yggdrasil.interface.YggInterface import YggInput, YggRpcServer


def get_fibonacci(n):
    r"""Compute the nth number of the Fibonacci sequence.

    Args:
        n (int): Index of the Fibonacci number in the Fibonacci sequence that
            should be returned.

    Returns:
        int: The nth Fibonacci number.

    """
    pprev = 0
    prev = 1
    result = 1
    fib_no = 1
    while fib_no < n:
        result = prev + pprev
        pprev = prev
        prev = result
        fib_no = fib_no + 1
    return result


def main():
    r"""Function to execute server communication and computation in a loop."""

    print('Hello from Python server!')

    # Get parameters
    inp = YggInput("params")
    retval, params = inp.recv()
    if not retval:
        raise RuntimeError('server(P): ERROR receiving parameters')
    print('server(P): Parameters = %s' % params)

    # Create server-side rpc conneciton using model name
    rpc = YggRpcServer("server", "%d", "%d")

    # Continue receiving requests until the connection is closed when all
    # clients have disconnected.
    while True:
        print('server(P): receiving...')
        retval, rpc_in = rpc.recv()
        if not retval:
            print('server(P): end of input')
            break

        # Compute fibonacci number
        n = rpc_in[0]
        print('server(P): Received request for Fibonacci number %d' % n)
        result = get_fibonacci(n)
        print('server(P): Sending response for Fibonacci number %d: %d' % (n, result))

        # Send response back
        flag = rpc.send(np.int32(result))
        if not flag:
            raise RuntimeError('server(P): ERROR sending')

    print('Goodbye from Python server')

    
if __name__ == '__main__':
    main()

import sys
import numpy as np
from yggdrasil.interface.YggInterface import (
    YggRpcClient, YggOutput)


def main(iterations):
    r"""Function to execute client communication with server that computes
    numbers in the Fibonacci sequence.

    Args:
        iterations (int): The number of Fibonacci numbers to log.

    """

    print('Hello from Python client: iterations = %d ' % iterations)

    # Set up connections matching yaml
    # RPC client-side connection will be $(server_name)_$(client_name)
    rpc = YggRpcClient("server_client", "%d", "%d")
    log = YggOutput("output_log", 'fib(%-2d) = %-2d\n')

    # Iterate over Fibonacci sequence
    for i in range(1, iterations + 1):
        
        # Call the server and receive response
        print('client(Python): Calling fib(%d)' % i)
        ret, result = rpc.call(np.int32(i))
        if not ret:
            raise RuntimeError('client(Python): RPC CALL ERROR')
        fib = result[0]
        print('client(Python): Response fib(%d) = %d' % (i, fib))

        # Log result by sending it to the log connection
        ret = log.send(np.int32(i), fib)
        if not ret:
            raise RuntimeError('client(Python): SEND ERROR')

    print('Goodbye from Python client')

    
if __name__ == '__main__':
    # Take number of iterations from the first argument
    main(int(sys.argv[1]))

(Example in other languages)

The interface server-side API call (YggRpcServer for Python), requires 3 input variables: the name of the server channel (this will be the name of the server model), a format string for input to the server model, and a format string for output from the server model. The client-side API call (YggRpcClient for Python), also requires 3 input variables: the name of the client channel (this is the name of the server model joined with the name of the client model by an underscore, <server>_<client>, a format string for input to the server model, and a format string for output form the server model. The last two arguments (the format strings) to both the server and client API calls should be the same.

In the server model YAML, the key/value pair is_server: True needs to be added to the model entry to indicate that the model will be called as a server and requires a set of RPC channels. In the client model YAML, the key/value pair client_of: <server_model_name> is required to indicate that the model will act as a client of the <server_model_name> model.

Model YAML:

---

model:
  name: server
  language: python
  args: ./src/server.py
  is_server: True  # Creates a RPC server queue called "server"
  inputs:
    name: params
    default_file:
      name: ./Input/server_params.txt
      filetype: ascii

---

model:
  name: client
  language: python
  args:
    - ./src/client.py
    - 3  # Pass the number of iterations that should be performed
  client_of: server  # Creates an RPC client queue "server_client"
  outputs: output_log

connections:
  input: output_log
  output: client_output.txt
  in_temp: True

(Example in other languages)

In addition to the RPC API call, the example server also has an input params. Models acting as servers can have as many inputs/outputs as desired in addition to the RPC connections. While the example input is not used to modify the output in this example, such a comm could be used to initialize a model with parameters and/or initial conditions.

Using Existing Inputs/Outputs

Models that have already been integrated via yggdrasil can also be turned into servers without modifying the code. Instead of passing a boolean to the is_server parameter, such models can provide a mapping with input and output parameters that explicitly outline which of a existing model’s inputs/outputs should be used for the RPC call. Receive/send calls to named input/output channels will then behave as receive/send calls on a server interface comm.

Todo

Example source code and YAML of server replacing an existing input/output

One Server, Two Clients

There is no limit on the number of clients that can connect to a single server. In the example below, the server is the same as above. The client code is also essentially the same except that it has been modified to take a client_index variable that provides information to differentiates between two clients using the same source code.

Model Code:

import numpy as np
from yggdrasil.interface.YggInterface import YggInput, YggRpcServer


def get_fibonacci(n):
    r"""Compute the nth number of the Fibonacci sequence.

    Args:
        n (int): Index of the Fibonacci number in the Fibonacci sequence that
            should be returned.

    Returns:
        int: The nth Fibonacci number.

    """
    pprev = 0
    prev = 1
    result = 1
    fib_no = 1
    while fib_no < n:
        result = prev + pprev
        pprev = prev
        prev = result
        fib_no = fib_no + 1
    return result


def main():
    r"""Function to execute server communication and computation in a loop."""

    print('Hello from Python server!')

    # Get parameters
    inp = YggInput("params")
    retval, params = inp.recv()
    if not retval:
        raise RuntimeError('server: ERROR receiving parameters')
    print('server: Parameters = %s' % params)

    # Create server-side rpc conneciton using model name
    rpc = YggRpcServer("server", "%d", "%d")

    # Continue receiving requests until the connection is closed when all
    # clients have disconnected.
    while True:
        print('server: receiving...')
        retval, rpc_in = rpc.recv()
        if not retval:
            print('server: end of input')
            break

        # Compute fibonacci number
        n = rpc_in[0]
        print('server: Received request for Fibonacci number %d' % n)
        result = get_fibonacci(n)
        print('server: Sending response for Fibonacci number %d: %d' % (n, result))

        # Send response back
        flag = rpc.send(np.int32(result))
        if not flag:
            raise RuntimeError('server: ERROR sending')

    print('Goodbye from Python server')

    
if __name__ == '__main__':
    main()

import sys
import numpy as np
from yggdrasil.interface.YggInterface import (
    YggRpcClient, YggOutput)


def main(iterations, client_index):
    r"""Function to execute client communication with server that computes
    numbers in the Fibonacci sequence.

    Args:
        iterations (int): The number of Fibonacci numbers to log.
        client_index (int): Index of the client in total list of clients.

    """

    print('Hello from Python client%d: iterations = %d ' % (client_index,
                                                            iterations))

    # Set up connections matching yaml
    # RPC client-side connection will be $(server_name)_$(client_name)
    rpc = YggRpcClient("server_client%d" % client_index, "%d", "%d")
    log = YggOutput("output_log%d" % client_index, 'fib(%-2d) = %-2d\n')

    # Iterate over Fibonacci sequence
    for i in range(1, iterations + 1):
        
        # Call the server and receive response
        print('client%d(Python): Calling fib(%d)' % (client_index, i))
        ret, result = rpc.call(np.int32(i))
        if not ret:
            raise RuntimeError('client%d(Python): RPC CALL ERROR' % client_index)
        fib = result[0]
        print('client%d(Python): Response fib(%d) = %d' % (client_index, i, fib))

        # Log result by sending it to the log connection
        ret = log.send(np.int32(i), fib)
        if not ret:
            raise RuntimeError('client%d(Python): SEND ERROR' % client_index)

    print('Goodbye from Python client%d' % client_index)

    
if __name__ == '__main__':
    # Take number of iterations from the first argument and the
    # client index from the second
    main(int(sys.argv[1]), int(sys.argv[2]))

(Example in other languages)

The server YAML is the same as above. The client YAML now has entries for two models which are both clients of the server model and call the same source code.

Model YAML:

---

model:
  name: server
  language: python
  args: ./src/server.py
  is_server: True  # Creates a RPC server queue called "server"
  inputs:
    name: params
    default_file:
      name: ./Input/server_params.txt
      filetype: ascii

---

models:
  - name: client1
    language: python
    args:
      - ./src/client.py
      - 3  # Pass the number of iterations that should be performed
      - 1  # Pass index of the client
    client_of: server  # Creates an RPC client queue "server_client"
    outputs: output_log1
  - name: client2
    language: python
    args:
      - ./src/client.py
      - 5  # Pass the number of iterations that should be performed
      - 2  # Pass index of the client
    client_of: server  # Creates an RPC client queue "server_client"
    outputs: output_log2

connections:
  - input: output_log1
    output: client_output1.txt
    in_temp: true
  - input: output_log2
    output: client_output2.txt
    in_temp: true

(Example in other languages)

During runtime, request messages from both clients will be routed to the server model which will process the requests in the order they are received.

Two Servers, Two Clients

There is also no limit on the number of copies of a server model that can be used to responsd to RPC requests from the clients. In the example below, the server and clients are the same as above, but 2 copies of the server model are run as specified by the model copies parameter in the server YAML.

Model YAML:

---

model:
  name: server
  language: python
  args: ./src/server.py
  is_server: True  # Creates a RPC server queue called "server"
  copies: 2
  inputs:
    name: params
    default_file:
      name: ./Input/server_params.txt
      filetype: ascii

---

models:
  - name: client1
    language: python
    args:
      - ./src/client.py
      - 3  # Pass the number of iterations that should be performed
      - 1  # Pass index of the client
    client_of: server  # Creates an RPC client queue "server_client"
    outputs: output_log1
  - name: client2
    language: python
    args:
      - ./src/client.py
      - 5  # Pass the number of iterations that should be performed
      - 2  # Pass index of the client
    client_of: server  # Creates an RPC client queue "server_client"
    outputs: output_log2

connections:
  - input: output_log1
    output: client_output1.txt
    in_temp: true
  - input: output_log2
    output: client_output2.txt
    in_temp: true

(Example in other languages)

This allow client requests to be returned twice as fast, but precludes any use of an internal state by the server model as there is no way for a client to be sure that the same server model is responding to its requests and only its requests.

Wrapped Function Server

Models that are created by letting yggdrasil automatically wrap a function can also act as servers and/or clients. In the example below, the model acting as a server is a very simple function that takes a string as an input and returns the same string and the client is a function that takes a string as an input, calls the server models with the input string and returns the response.

When a client model is autowrapped from a function, additional care must be taken so that the client RPC comm can be reused during each call to the model. In interpreted models (Python, R, MATLAB), this is done by passing the keyword global_scope to the RPC client interface initialization function (YggRpcClient in Python). In compiled models (C, C++, Fortran), this is done by framing RPC client interface initialization calls with the WITH_GLOBAL_SCOPE macro (see the language specific versions of this example for specifics).

Model Code:

def model_function(in_buf):
    print("server(Python): %s" % in_buf)
    out_buf = in_buf
    return out_buf

from yggdrasil.languages.Python.YggInterface import YggRpcClient


def model_function(in_buf):
    # The global_scope keyword is required to ensure that the comm persists
    # between function calls
    rpc = YggRpcClient('server_client', global_scope=True)
    print("client(Python): %s" % in_buf)
    ret, result = rpc.call(in_buf)
    if not ret:
        raise RuntimeError('client(Python): RPC CALL ERROR')
    out_buf = result
    return out_buf

(Example in other languages)

The RPC connection between the server and the client is controlled by the same is_server and client_of YAML parameters as before.

Model YAML:

model:
  name: server
  language: python
  args: ./src/server.py
  function: model_function
  is_server: True

model:
  name: client
  language: python
  args: ./src/client.py
  function: model_function
  client_of: server
  inputs:
    name: in_buf
    default_file:
      name: ./Input/input.txt
      filetype: ascii
  outputs:
    name: out_buf
    default_file:
      name: ./client_output.txt
      in_temp: true

(Example in other languages)

By default, all inputs to a wrapped server function will be used in the RPC call. However if only some of the inputs should be passed in by the RPC calls, they can be specified explicitly by providing the is_server parameter with a map that contains input and output parameters that map to the names of function input/output variables (as in the case of using existing input/output channels above).