Remote Procedure Call RPC

Introduction

Remote Procedure Call (RPC) is a mechanism which allows a program to invoke a function that is defined in another address space. If a user, A, writes a function and shares it with another user B, then B can invoke the shared function in A's program. The return value of the function is retrieved by B, which can then be used in B's program.

RPC is implemented using the Source Academy Module feature. The module is named 'rpc' and exposes three functions, namely connect, share and executeAfter.

The RPC also allows sharing of values in Source programs. These include numbers, strings, booleans, null and undefined. The sharing of arrays of arbitrary nesting is also allowed, along with lists and pairs which resolve into arrays themselves.

User Documentation

To start off, the functions mentioned above must be imported from the module 'rpc' using Source's import statement. The behaviour of the aforementioned functions is described as follows: -

• share - Returns a promise that resolves to a token that uniquely identifies the shared data or function. share accepts data or functions as input and runs asynchronously. The obtained token, when shared to another user, can be supplied as input to the connect function to retrieve the shared data or function.

  • Parameter: input - Any value that occurs in a Source program.
  • Returns: A promise that resolves to a token that uniquely identifies the shared content.

• connect - Returns a promise that resolves to the content that is uniquely identified by the input token. The function throws an error if the input is invalid. connect executes asynchronously like share.

  • Parameter: token - A string token that uniquely identifies some shared content.
  • Returns: A promise that resolves into the data or function that is identified by the input token.
  • Throws: An error if the token is invalid.

• executeAfter - Executes a call-back function after a promise is resolved. The value that the promise resolves into is supplied as input to the call-back function. This function must be used to deal with the returned promises of connect and share. Using promises as normal values in a program without executeAfter can lead to undefined behaviour.

  • Parameter: promise - A promise that resolves into some data or function.
  • Parameter: call-back - A call-back function that executes after the promise is resolved. The resolved value is supplied as argument to this function.
  • Returns: The return value of the call-back, if any. Using this return value synchronously can lead to undefined behaviour.

The functions share and connect are the core of this module, and their asynchronous behaviour is achieved by using the executeAfter function.

The following are code examples of correct module usage: -

\* USER A *\
const xs = list(1, 2, 3, 4, 5);
const token = share(xs);
executeAfter(token, display);

display('Sharing initiated');

\* A token 's' gets displayed in A's REPL after `Sharing initiated` is first printed. 'Sharing initiated' is printed first since executeAfter needs to wait for the promise returned by share to get resolved. *\

\* USER B *\
\\ Assume the constant s is the token shared by A to B.
const dataPromise = connect(s);
executeAfter(dataPromise, display);

\* The list of numbers from 1 to 5 gets displayed in B's REPL *\

Prerequisites and Resources

This system requires an understanding and familiarity with a broad range of topics. The following is a non-exhaustive but comprehensive list of topics and resources that should help a developer get started:

Since this project is written in Typescript, familiarity with Typescript/Javascript (JS) is required.

Topic	Reference Resource
Source Academy Modules system	Modules Wiki
Remote Procedure Calls	Wikipedia Article
How Javascript is executed by the browser	How Javascript works in the browser
Asynchronous and Concurrent program execution	Video by Hussein Nasser
Javascript Event Loop	The JavaScript Event Loop explained
Firestore Realtime Database	Quickstart Guide
JavaScript Promises and async-await	Series of articles

System Overview

Semantical Specifications

Functions explanation