Adding Designer's Interface Clients

Client processes are compiled into the interface, which means that they will most easily be written in C (same as the interface). The function arguments, and what data is passed around is explained here. Data structures are not explained here, but can be found in client_options.h.

client prototype

typedef int (client_function)(client_options *cptr,
                              server_submit *s_sub, server_reply *s_rep,
                              void *vptr,
                              double *best_inp, double *best_out);

All clients use this prototype. Client functions return 0 on normal termination.

optr (input): This structure contains all settings needed by the client.
s_sub (input): The client calls this function (passed from a pointer) to submit jobs for the server.
s_rep (input): The client calls this function (passed from a pointer) to receive data back from the server.
vptr (input): This structure contains options for the server. This structure is not for use by the client, and is merely passed along when calling s_sub and s_rep.
best_inp (output): This is a pointer to hold the inputs corresponding to the ``best'' point found. Space for the data has been made by the Designer's Interface.
best_out (output): This is a pointer to hold the outputs corresponding to the ``best'' point found. Space for the data has been made by the Designer's Interface.

`server_submit` and `server_reply`

These functions are called by the client process to get information from the server.

`server_submit`

typedef int (server_submit)(server_io *s_io, void *vptr);

Request evaluation of the server at the point specified by s_io. Evaluation results are obtained via server_reply. server_submit returns 0 upon normal execution.

s_io (input): This structure contains the input point. The structure is also used by the server to return the output, so the client should not release memory
vptr (input): The server data vptr from the call to the client is passed here.

`server_reply`

typedef int (server_reply)(server_io **s_io_ptr, void *vptr);

Receive data from an evaluation of the server function previously requested using server_submit. server_reply returns 0 upon normal execution.

s_io_ptr (output): This returns a pointer to a server input/output structure (previously passed using server_submit). The structure contains both the input and output variables from the call to the server.
vptr (input): The server data vptr from the call to the client is passed here.

Additional Implementation Notes

All fields relating to input and output variables are processed by the individual client. The interface mediates settings only to ensure consistency. This means that fields set in the client specification file, such as scale and derivative_step, need to be managed in the client.

It is the client's responsibility to make sure that all required parameters have been supplied. The interface ensures that only valid parameters are set, but it does not know which ones (if any) are required.

Each Designer's Interface client requires an associated specification file, which describes what parameters and types fields the client is able to process. This file resides in the interface subdirectory ./clients/specs/.

When a new client is added to the interface, two design interface files need editing. These are ./clients/makefile and ./clients/client_list.c in the di directory.

A target is added to the makefile for each client source file. These targets take the form:
$(TARGET): $(TARGET)(client_dir/client_source_name.o)

The links to the client are made in client_list.c. Essentially, the new client is added to a list of valid clients in the interface. Three changes are made to the file.

The number of known clients is incremented. This is set in a #define macro which looks like:
#define N_KNOWN_CLIENTS 4
The client function prototype is declared. Since all clients have the same functional interface, they should all match the client_function typedef.
extern client_function client_function_call;
The new client is added to the client list known_clients. The number of clients has already been changed, so only a new entry needs to be added. The entry looks like:
{"client_name", client_function_call}
where the client_name is used in the startup file, and client_name.spec names the specification file in the ./clients/specs/ directory.

Additional Documents

C include file client_options.h
client specification file

Return to Designer's Interface Overview.