2007-02 Design Notes

Table of contents

Introduction

We can say that SCS architecture is agent oriented ( Wikipedia: Multi Agent System ).
All agents collaborate and create a team : SCS.

Agents

About Agents

Link for separate page: 2007-02 About Agentsv & Communication API .

Agents list

Key ones:

Rest:

How do they work ?

Agents collaborate in following way:

  • TODO

Design

Idea. Abstraction model drawing.
( G - GUI is a subtype of UI - User Interface. For more info look at agents list.)

Agents speak to each other.
It's abstraction model realized thought api.

Implementations

Abstraction model can be implemented in many different ways,
but implementation details are always hidden behind communication api structure and in effect… transparent and invisible for agents.

Current implementations are:

  • Base on standard I/O
  • Based in Simple TCP/IP Queue

standard i/o

Communication API implementation based on I/O standard streams
which main purpose is to boost agents development.

It can be also used to run agents in a lot of many simple tasks.
More information about that feature you can find on draft page: 2007-03-02 Stdio Communication Api's Implementation .

queue simple tcp/ip


( G - GUI is a subtype of UI - User Interface. For more info look at agents list.)
That implementation organises all agents around one Simple TCP/IP Queue agent.
Of course, centralized structure is hidden behind communication api and invisible for other agents.
It's current default implementation.

Communication API


This point describes api, through which Agents speak to each other.

Example of use

int ret;
long id, len;
const long bufsize = 1024 * 1024;
char *buf = new char[bufsize];
while( condition ){
    len = bufsize;
    id = scsrecvas(MY_TYPE_NUMBER, buf, &len, 0);
    if( id < 0 ) { scsraiseerror("Error");  return ret; }
    /* 
       processing data
     */
    ret = scssendto(TARGET_AGENT, buf, len, 0);
    if( ret != 0 ) { scsraiseerror("Error");  return ret; };
    ret = scsconfirm(MY_TYPE_NUMBER, id, 0);
    if( ret != 0 ) { scsraiseerror("Error");  return ret; };
};

Receive As

Receive As - long scsrecvas(long who, void *buf, long *len, int flags)
By this function agent volunteers to receive message as one of who agents.
who - "as who?" agent want to receive (TODOANG -> "as who?" ~ jako kto )
buf
len set this as size of buffer. Function sets this as size of received data.
flags - now always 0
Returns On success : message id (positive number >0 ) . On fail: negative number.

Example of use:
Agent J want to receive message to him:

id = scsrecvas( SCS_JUDGE, buf, bufsize, 0);
if( id < 0 ) { scsraiseerror(...);  return ret; }

Send To

Send To - int scssendto(long towho, const void *buf, long len, int flags)
towho - to what agent (addressee)
buf - buffer with data
len - data size
flags - now always 0
Returns 0 on success.

Example of use:
Agent Ch sends message to agent J:

ret= scssendto( SCS_JUDGE, buf, len, 0);
if( ret != 0 ) { scsraiseerror(...);  return ret; };

Confirm

Confirm - int scsconfirm(long who, long id, int flags)
By this function agent confirms that previously received message was processed.
who - who agent is
id - received message id
flags - now always 0
Returns On success : 0 .

Example of use:
Agent J want to receive message to him:

id = scsrecvas( SCS_JUDGE, buf, bufsize, 0);
/*
...
here is processing
...
*/
ret = scsconfirm(SCS_JUDGE, id, 0);
if( ret != 0 ) { scsraiseerror(...);  return ret; };

Queue (Q)


Link for separate page: 2007-02 Agent Queue.

Links to older versions

Queue Simple TCP/IP

This Queue implementation is realized thought one thread TCP/IP server with client implementation in communication protocol.
This implementation is tolerant and is case insensitive. But you should be care full about case sensitive, cause maybe in the future protocol implementation will not be so nice.


Locking is a mechanism that protect data flow from data processing vulnerabilities.
The algorithm is simple:

  • Received message is locked
  • When there is no answer for some longer period of time.
    • Watchdog Agent checks what is going on and try to fix it. (For example by restarting crashed agent).
    • Message is unlocked for processing.
  • When data processing success.
    • Success is confirmed.
    • Data message is removed from queue.

Queue Protocol version 0.01

Important notes :

When line is being send i.e. "Hi.\n" , the c-string terminating zero is not send !.
In that case only only four bytes will be send {'H', 'i', '.', '\n'}.

Both newline ( "\n" ) terminators are accepted: <CR> and <CR><LF>.

Code Decimal Octal Hexadecimal printf notation
<CR> 13 015 D "\013" and "\xD"
<LF> 10 012 A "\012" and "\xA"

So both are correct "\xA" and "\xD\xA"

Queue Communication Protocol looks as following.

Sending dialog

Sending dialog is a dialog that enables to put something into Queue.
In other words to send message to any of agents of given type.
Here how dialog look line.

Client: Hi.\n
Server: Hi.\n
Client: I speak SCS Queue protocol version 0.01.\n
Server: OK.\n (or Bye.\n)
Client: I want to send to any agent of type number 5.\n - (5 is an example number, It could be any integer between 0 and 216)
Server: OK.\n (or Bye.\n)
Client: Data size is 1234.\n - 1234 is an example number. It can be any integer between 0 and 231
Server: OK.\n (or Bye.\n)
Client: Data:\n
Client: HERE IS DATA
Client: .\n - after data there is a dot and newline char
Server: OK.\n (If error then:/ Fail!\n or Bye.\n)
Client: Bye.\n
Server: Bye.\n

So, Client can assume that everything was OK, only if received four times OK.\n .
When client receives any Bye.\n from server it should answer immediately by Bye.\n and close connection.

Receiving dialog

Receiving dialog enables agent to receive message that was addressed to it and lock it.
In other words to pop receive data from Queue and Lock it.

Client: Hi.\n
Server: Hi.\n
Client: I speak SCS Queue protocol version 0.01.\n
Server: OK.\n (or Bye.\n)
Client: I'm agent of type number 5.\n - (5 is an example number, It could be any integer between 0 and 216)
Server: OK.\n (or Bye.\n)
Client: I want to receive.\n
Server: OK.\n (or Bye.\n)
Server: Data size is 1234. Data ID is 456.\n - 456, 1234 are an example numbers. They can be any integer between 0 and 231
Client: OK.\n (or Bye.\n)
Server: Data:\n
Server: HERE IS DATA
Server: .\n - after data there is a dot and newline char
Client: OK.\n
Server: Data is locked.\n
Server: Bye.\n
Client: Bye.\n

So, Client can assume that everything was OK, only if received three times OK.\n and one time \Data is locked.\n .
Server can assume that everything was OK, only if received two times OK.\n .
When client receives any Bye.\n from server it should answer immediately by Bye.\n and close
connection.

Confirmation of success in data processing.

Confirmation is needed to provide Queue information that can remove locked massage from queue.

Client: Hi.\n
Server: Hi.\n
Client: I speak SCS Queue protocol version 0.01.\n
Server: OK.\n (or Bye.\n)
Client: I'm agent of type number 5.\n - (5 is an example number, It could be any integer between 0 and 216)
Server: OK.\n (or Bye.\n)
Client: I confirm a success in processing data, which ID is 456.\n - (456 is an example number, It could be any integer between 0 and 231)
Server: OK.\n (or Bye.\n)
Client: Bye.\n
Server: Bye.\n

So, Client can assume that everything was OK, only if received three times OK.\n .
When client receives any Bye.\n from server it should answer immediately by Bye.\n and close connection.

Compiler (C)


Link for separate page: 2007-02 Agent Compiler.

Links to older versions

Joachime, poniżej jest tylko szkic ,czuj się swobodny w zmienianiu i refaktoryzacji :) .

Aim.

Compiler aim is to compile given source into binary.

What does Compiler Agent do ?

Messages flow
  1. Receives sources
  2. Compiles it
    1. If. Success sends binaries to Checker Agent
    2. If. Fail sends compilation problem info to User Interface Agent
  3. Confirms processing (according communication api protocol)

Message format

Compiler Agent accept messages in following format (put under X suitable data):

Version: 0.01
User: X
Problem set: X
Problem name: X
Source size: X
Source data :
X
End.

Notes:

Binary data begins after new line separator and next information is after newline sepearator.
So, use new line separator before and after data chunk.

The same as in Agent Queue two newline separators are acceptable: <CR> and <CR><LF>

Checker (Ch)


Link for separate page: 2007-02 Agent Checker.

Purpose

Checker checks users problem solution (given as binary program) and sends report to Judge.

What does Checker Agent do ?

Messages flow
  1. Receives binary program representation.
  2. Checks program.
    1. I.e. on set of tests files
  3. Prepares report from checking.
  4. Sends report to Judge.

Message format.

Checker Agent accept messages in following format (put under X suitable data):

Version: 0.01
User: X
Problem set: X
Problem name: X
Binary size: X
Binary data :
X
End.

Notes:

Binary data begins after new line separator and next information is after newline sepearator.
So, use new line separator before and after data chunk.

The same as in Agent Queue two newline separators are acceptable: <CR> and <CR><LF> .

Preprocessor (Pre)


Link for separate page: 2007-02 Agent Preprocessor

Purpose

The main purpose of this agent is to preprocess incoming data from user interface agents into format suitable for further processing (i.e. understandable for Compiler agent).

Another purpose is to give a possibility to implement easily some new functionalities without implementing whole agent, but just by modifying a present one.

Watchdog (W)


Link for separate page: note:2007-02-agent-watchdog.

Page to be included note:2007-02-agent-watchdog can not be found!

Judge (J)


Link for separate page: note:2007-02-agent-judge.

Page to be included note:2007-02-agent-judge can not be found!

UI (U)


Link for separate page: note:2007-02-agent-ui.

Page to be included note:2007-02-agent-ui can not be found!

GUI (G)


Link for separate page: note:2007-02-agent-gui.

Page to be included note:2007-02-agent-gui can not be found!

Database (DB)


Link for separate page: 2007 02 Agent Db.

Aim

To log all events:

  • To provide stand up after crash.

Keep data for future usage:

  • WWW server
  • Statistics
  • Code archive
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-Share Alike 2.5 License.