In this section we give an overview of how the LADCCA system operates, describing the server and client objects and operations that make it work. The @command{ladccad} server must be running in order for clients to participate in the system; clients cannot interoperate soley between themselves. The server maintains a list of connected clients and a list of projects with which these clients are associated.
The server and clients exchange events and configs over their connections. There is one, and only one, bi-directional connection between a client and the server. The transport for this connection is currently TCP.
An event is a very simple object having two relevant properties: a type and an
optional arbitrary character string. The type defines what the event means to the recipient,
and the string allows additional information to be included with it. For
example, if a client wishes the server to save the current project, it sends a
CCA_Save event to the server. While saving the project, the server
may wish to tell a client to save its data in a certain directory. To so,
it sends a CCA_Save_File event to the client with a string containing the
name of a directory into which the client should save its data files.
Clients can save data on the server if they wish. To do this, the
client declares that it wants to save data on the server when it initialises the server connection
and then later sends one or more configs to the server. A config is
also a very simple object. It has a client-unique character string key, and
a value of arbitrary size and type (well, almost arbitrary; its size must
be able to be described by a uint32_t integer due to byte-order conversions
done when sending data over the network.)
In this section we will examine a typical session in some detail, describing the server and client operations that take place. In the session, the server is started, a number of clients connect, the session is saved and then restored.
Before all else, the user starts the server. It starts up and begins listening for connections from clients. It doesn't do much else.
The user then starts a JACK client program. It opens a connection to the server and provides it with all information that the server will need to run the application again. This information includes: the current directory that the user was in when they ran the program, the command line that started the application and the class of the client (a character string that the client application provides the initialisation routine that will never change over all initialisations.)
With this information is included a set
of flags that describe the client to the server. This particular
client saves data to files and wants the server to tell it where to
save files when the project is saved, so it has the
CCA_Config_File flag set.
The client library starts two threads for communication with the server, one for sending data and the other for recieving. It also sends, along with the client supplied data, a number of parameters that were extracted from the client's command line options before it checked them. This optionally includes the name of the project that the client should initially be associated with and a 128-bit, world-unique identifier for this particular client instance (the LADCCCA ID.)
Server-side, the server wakes up to the fact that a new connection has arrived and immediately adds it to a list of open connections and then goes back to waiting. When the client sends the requisite information, the server looks at it and decides what to do with the client. This client has not requested a specific project to which it should be connected. However, there are no existing projects so the server creates a new project with the name `project-1' in the directory `/home/user/audio-projects/project-1' (assuming the user didn't specify a different default directory when running configure.) It also generates a new LADCCA ID for the client. It then adds the client to the new project and goes back to listening.
The client then connects up to the JACK server and, after having done this,
sends a CCA_Jack_Client_Name event to the server with the name that
it registered to JACK with as the string. This notifies the server that it
is a JACK client and needs its JACK port connections saved and restored.
The server will now pay attention to any activity regarding the client
(ie, port creation and destruction and port connection and disconnection.)
The user then starts a second client that uses the ALSA sequencer interface
and wishes to save data on the server. It connects to the server with a
different class to the JACK client and with the
CCA_Config_Data_Set flag set.
The server sees that this client also didn't specify a project, and so adds it to the first available project; the same one as the previous project, `project-1'. It also sees that the client wants to store data on the server, and so it creates a directory within the project directory for this data to be stored in and creates a database-style object to manage the client's data.
The client then connects to the ALSA sequencer and sends its client ID to
the server in the first character of the string of a
CCA_Alsa_Client_Name event. The server regards this similarly to
the other client's JACK client name.
After the user has done some work in the two clients, they want to save
their work. They click a button on one of the clients (or something similar)
and the client sends a CCA_Save event to server. The server recieves
this and then iterates through each client in the project and checks its
flags. The JACK client saves data by itself (it has the
CCA_Config_File flag set,) so the server creates a
directory under the project directory for it to save in and then sends a
CCA_Save_File event to the client with a string containing the name
of the directory it made. The client recieves the event and saves its data into
the specified directory.
Next, the server examines the ALSA client. It wishes to save data on the
server, so the server sends a CCA_Save_Data_Set to the client. With
all of the clients iterated through, it now saves all the information it
needs to be able to restore them; their working directory, command line
options, etc. In order to do this, it asks the JACK server
to find the connections for the JACK client, and asks the ALSA sequencer to
find the connections for the ALSA client. It uses the client name and ID
that both clients sent to the server after opening their connections to the
respective systems. All of this information is stored
in a file under the project's directory. When this is done, the server goes
back to listening for events and configs.
The client, meanwhile,
has recieved the CCA_Save_Data_Set event and sends back a number of
configs to the server. When it has sent all the data it wishes to be saved,
it sends back a CCA_Save_Data_Set event. The server passes all of
the configs to the object managing the data store for the ALSA client.
When the server recieves the CCA_Save_Data_Set event
from the client, it tells the data store to write the data to
disk. The save is now complete.
Unfortunately for the user, the ALSA client crashes. The server detects
that the client has disconnected, and puts the client on a list of lost
clients for the project. The user then starts another copy of the client,
which connects to the server in the same way it did before. This time,
however, the server checks through the list of lost clients and finds that
the class of the new client matches the class of the lost client and so it
resumes the lost client using the new one. It gives it the 128-bit ID of
the lost client, adds it to the project, and then sends a
CCA_Restore_Data_Set event to the client. The client then cleans
itself up, ready to recieve the data set. The server sends the client the
configs, and then another CCA_Restore_Data_Set event. The client
recieves this data and its state has been restored that of the client that
crashed.
The user can stop this behaviour by specifying the @option{--ladcca-no-autoresume} option on the client's command line.
The user has to go off and do other things, and so they close down
the clients and the server. Some time later, the user comes back and
wants to start working again so first, as always, they start up the server.
They then start the @command{ladcca_control} program. This is a text
interface command program for controlling the server. They get a command
prompt and into it type restore
/home/user/audio-projects/project-1. The ladcca_control client sends
a CCA_Restore event to the server with the specified directory as the
string. The server opens the file that it saved before, and reads in all
the information about the project and its clients. It creates a new project
with this information. The clients are created as lost clients, however.
The server then iterates through each client and starts a new copy of it using the information provided when the original client connected. It also adds some command line options that are extracted by the client library. These specify the LADCCA ID of the client, the project name that it should be connecting to and the server's hostname and port. It then goes back to waiting.
The new JACK client then connects to the server as normal. When the server
recieves it connection, it checks the client against the project's list of
lost clients. This time, however, it has its ID specified, so the server
will only resume a client with a matching ID. Lo and behold, such a client
exists. The server resumes the old JACK client, telling it to load its
state from the files in the project directory that the client previously
stored. It does so with a CCA_Restore_File event with the string as
the directory name. The ALSA client does exactly the same, except having
its data restored through CCA_Restore_Data_Set as described above.
Only one thing remains for the clients to be fully restored: the JACK and
ALSA sequencer connections. This happens when the clients send their
CCA_Jack_Client_Name and CCA_Alsa_Client_ID events. The
connections are stored with the LADCCA ID rather than the JACK
client name or ALSA client ID. When the client registers its name or ID,
the connections are converted from the LADCCA ID to the JACK client name or
ALSA client ID, and the connections are restored. It also pays attention to
connections to other clients within the same project, converting between JACK client
names, ALSA client IDs and LADCCA IDs as appropriate.
Go to the first, previous, next, last section, table of contents.