SmartFlow 2 preliminary notes
------------------------------

General
*******
NTP required, or any synchronisation methods which does not "go
back in past".

Must make an SmartFlow v1 emulation layer on the top of the SF 2
( API compatible, so that a single recompilation make the old clients
works with the new system )

Threads must be used, and overused !

Server Definition :
*******************
   Tasks of the server : 
- Establish connection with the other servers on the smartflow,
- Broadcast publish its current clients characteristics (in/out flow)
- Rerun a client that is crashed ( with a respawn time limit )
   -> Track informations about current clients
- Track the asyncronous signals emitted by consumer clients to other provider
clients (flow control), so that if a client crash when it has stopped a
provider, the server can by itself resume the stopped provider.
- Take care of shared memory segments : allocation/unallocation/clean, 
give the adress back to a client.

One server is run for each triplet { machine , user, application }. The files
it use are : 

   /tmp/sf_<application>/sf_<user>/pid
   /tmp/sf_<application>/sf_<user>/socket

The subdirectory sf_<user> is marked <rwx --- ---> so that only the <user> 
can see the socket, to avoid another system user to send commands to the server.

Once started, the server create the pid file and the socket and connect to the
whole smartflow network. Upon success, it detach itself thus leaving the
control to the caller.

Client Definition : 
*******************
The steps when running a client : 
    
              Run client
                   | 
     Check if a server is running ----------  spawn a server
                   |                  no            |
               yes |                                |
                   |                                |
                   |<-------------- < --------------/
                   |
     connect to server (sf_init)
                   |
                   | 
             create flows
                   |
                   |
               Main loop


- The client communicate with the server with a socket.  If the server doesn't
respond anymore, the client must rerun it.

- If two servers are run on the same node for the same user/password,  one must
commit suicid, letting the other in control.

- All data blocks are in shared memory segments, even if there is only one
client using the data in a given node. The overhead of creating a shared
segment by creating a user segment is small, and the r/w access to the segment
once it has been created is negligeable.

  Flow control : 
  ---------------
A consumer client must be able with a special call to STOP the provider from
sending data.

The provider then stop sending for ALL the clients.

The initial consumer client must then send a START signal to start the sending
again. If the client crash after sending a STOP signal, then it is the job of
the server of the crashed client node to "unlock" the provider by sending a
START signal, replacing the dead client.

For this mechanism to take place, the provider has to accept it, by a
command-line argument :
--allow-flowcontrol

A provider can be started in the "stop" state with an argument like this :
--wait-client 3

It means that the provider will initially start to send data after it received
3 "start" signals from 3 different clients.
A "Start" signal while the provider is sending has no effect, a "stop" signal
while the provider is stopped has no effect either. 

Flow Definition :
*******************
The primary key for a flow provider is :
  { name,           ex "VIDEO IN"
    group,          ex "CAM1"
    user,           ex "John"
    application     ex "MeetingRoom"
  }

- A flow has a TYPE (ex "VIDEO", "AUDIO", "MULTIAUDIO", "RAW"...).
A user can create its own type, by default these will be considered as raw data.
Plugins can be however developped for some special handling of a particular type
(ex : audio conversion)

- The name is the key to connect flows between them ( A consumer client will
request a "VIDEO IN" flow in input)
- The group is a finner tune of the flow name (A consumer client could request a
VIDEO IN flow in input but only if the flow belongs to thew group "CAM1".
That allows several "VIDEO IN" flow to exist without collision).
- The user exists for authentication purpose. It has not to be the name of a
system user account. (It can be anyway, if the authentication layer needs it).
- The "application" allows to have two different SmartFlow system running on the same
physical network.

- All flows are indexed by timestamp. (That's why NTP is required)

  Take-Over :
  ------------
If during the smartflow run , it is determined that for some reasons there is
two or more provider for a flow, then one of the duplicate flow provider must die.
The SmartFlow must then :
   -> Determine the one who will die,
   -> Move all its connection to the other provider,
   -> Kill the obsolete provider.
From the client point of view, nothing has changed : We do not want to handle
this case in the client code.

  Auto-conversion :
  -----------------
  For eg. an AUDIO flow type can provide several audio formats. It's the role of
the server to convert the data between a provider and its consumers if needed.
To achieve this, a conversion plugin exists.
The task of this plugin ( which is specific to a flow type ) is to
determine the parameters inside the flow, and then spawn an appropriate
conversion client between the provider and the consumer to handle the
conversion work.

Source core :
************** 
( .c, .h are source file, .so is shared libraries )

SmartFlow2/doc
SmartFlow2/src/lib              : Core library, .c .h -> .so
SmartFlow2/src/admin            : All user programs (xsfcc, codegen, ...)
SmartFlow2/src/misc             : Other sources (drivers...)
SmartFlow2/src/plugins/com      : Communication plugins sources,.c .h  -> .so
SmartFlow2/src/plugins/auth     : authentication plugins sources,.c .h -> .so
SmartFlow2/src/plugins/loadbal  : loadbalancing plugins sources, .c .h -> .so
SmartFlow2/src/clients/audio .. : Clients directories, can be subdivided
                      /video ..
SmartFlow2/INSTALL
SmartFlow2/README
SmartFlow2/autogen.sh         : autoconf/automake script
SmartFlow2/sfInstaller/*      : The graphical installer files
SmartFlow2/setup              : The script to run for distribution auto-installation


- Use autoconf/automake
- The main SmartFlow library is a shared object, eg. libsflib.so.
  It contains all the smartflow functions.
- It can be extended by plugins :

- Communication plugins :  Define an interface for sending/receiving data on
the network. Base plugin : TCP transport. Possible additionnal layers : UDP,
SSH tunnel, ipsec...

- Authentication plugin :  Each client must authenticaticate its party before
sending it data. Base plugin : Trust everybody. Possible additional layers :
PKI, PGP, shared secret...

- Loadbalancing plugin  : Policy to move clients from nodes to node,
depending of an evaluation of :
     1/ each client processing needs and
     2/ host processing power.
Base plugin : Do not care (clients do not migrate).Additional layers : Use the
linux bogomips values to move clients across nodes.

The "converters clients" are actually SmartFlow clients which are localy spawned
by a server when it needs to convert a flow from a format to another.
It communicate with the other clients on the same node by shared memory.

Arguments to pass to gcc :
  For final version  :    -fomit-frame-pointer -O2 -Wall ->final optimisation
  For creating a .so :    -fPIC                          ->relocatable code

Arguments to pass to ld :
  For final version  :    -O2
  For creating a .so :    -shared -Wl,soname,libsflib.so.2 -o libsflib.so.2.0.1
  (example with libsflib.so)

Strip the result to reduce size
( maybe put these parameters in a configure option --enable-release )

Installation core :
********************

Installation in <subdir> ( default /usr/local/smartspace )
<subdir>/bin               -> Admin & user programs
<subdir>/sf_clients        -> Smartflow clients
<subdir>/sf_clients/conv   -> Smartflow clients to convert formats
<subdir>/doc/smartflow     -> Documentation
<subdir>/lib               -> Shared libraries
<subdir>/lib/sf_plugins    -> SO plugins
<subdir>/include/smartflow -> Include files to develop new clients or plugins

- The bin directory must be in the path
- The lib directory must be either in LD_LIBRARY_PATH or 
  in /etc/ld.so.conf in linux ( what for other unixes ? )


Things to do :
***************
- Define the way to connect the client to a server once it has been spawned
  on a node
- Define how the server will discover the other participating nodes in the
  smartflow ( must work on a non-broadcast capable network )
- Define the list and content of every messages exchanged between servers
- Define the fields of all internal structure, in particular the "flow"
  structure
- Define how the client will connect themselves to each others
  (communication layer ) and in particular, what are the information
   needed to do that ( eg. : connection type : TCP imply load the TCP plugin
   who explore the remaining of the message to find the parameters)
- Define all the messages between client and server on the local node
  (eg. creation of a shared segment )
- Define the format of all the needed segments ( data, but also administrative)
- How to do the IPC key management

- Create the API prototype

- Code it !
- Test it !
- Trash that, and code it again !
- Release it !
- Collect the awards ;-)
