3. Interprocess communications

3.1 Overview

A production kdb+ system may have several q processes, possibly on several machines. These communicate via TCP/IP. Any q process can communicate with any other q process as long as it is accessible on the network and is listening for connections.

  • a server process listens for connections and processes any requests
  • a client process initiates the connection and sends commands to be executed

Client and server can be on the same machine or on different machines. A process can be both a client and a server.

A communication can be synchronous (wait for a result to be returned) or asynchronous (no wait and no result returned).

3.2 Initialize server

A q server is initialized by specifying the port to listen on, with either a command-line parameter or a session command.

..$ q -p 5001          / command line
q)\p 5001              / session command

3.3 Communication handle

A communication handle is a symbol that starts with : and has the form:

`:[server]:port
where the server is optional, and port is a port number. The server need not be given if on the same machine. Examples:
`::5001                    / server on same machine as client
`:genie:5001               / server on machine genie
`:198.168.1.56:5001        / server on given IP address
`:www.example.com:5001     / server at www.example.com
The function hopen starts a connection, and returns an integer connection handle. This handle is used for all subsequent client requests.
q)h:hopen `::5001
q)h "3?20"
1 12 9
q)hclose h

3.4 Synchronous/asynchronous

Where the connection handle is used as defined (it will be a positive integer), the client request is synchronous. In this case, the client waits for the result from the server before continuing execution. The result from the server is the result of the client request.

Where the negative of the connection handle is used, the client request is asynchronous. In this case, the request is sent to the server, but the client does not wait or get a result from the server. This is done when a result is not required by the client.

q)h:hopen `::5001
q)(neg h) "a:3?20"          / send asynchronously, no result
q)(neg h) "a"               / again no result
q)h "a"                     / synchronous, with result
0 17 14

3.5 Message formats

There are two message formats:

  • a string containing a q expression to be executed on the server
  • a list (function; arg1; arg2; ...) where the function is to be applied with the given arguments
    q)h "2 3 5 + 10 20 30"         / send q expression
    12 23 35
    q)h (+;2 3 5;10 20 30)         / send function and its arguments
    12 23 35
    
    If a function name is given, this is called on the server.
    q)h ("mydef";2 3 5;10 20 30)   / call function mydef with these arguments
    
    There are examples in the Realtime Database chapter, where a process receives a data feed and posts to subscribers by calling an update function in the subscriber.

3.6 HTTP connections

A q server can also be accessed via HTTP. To try this, run a q server on your machine with port 5001. Then, load a web browser, and go to http://localhost:5001. You can now see the names defined in the base context.