//-----------------------------------------------------------------------------
                                    Введение
//-----------------------------------------------------------------------------

Протокол передачи данных между узлами распределённой нейросети
(Data Transfer Protocol between the nodes in a Distributed Neural Network),
коротко DTPDNN.

//-----------------------------------------------------------------------------
                                    Потоки
//-----------------------------------------------------------------------------

Минимальная единица данных при передаче между двумя узлами называется потоком.
Поток представляет собой XML-документ с родительским элементом stream:

<stream></stream>

//-----------------------------------------------------------------------------
                                    Инициализация
//-----------------------------------------------------------------------------

При соединении двух узлов должна произойти инициализация протокола.
При инициализации протокола указывается его версия, а также уникальный
идентификатор клиента.

Примеры версии протокола:
1.0, 1.2.5, 2RC и т.д.

Уникальный идентификатор должен представлять собой MD5-хеш.

Первый поток должен быть отправлен инициализатором соединения:
<stream>
	<initialization>
		<protocol>1.0</protocol>
		<uid>b52c96bea30646abf8170f333bbd42b9</uid>
	</initialization>
</stream>

Поток ответа может содержать признак успешной инициализации или сообщение
о возникшей ошибке.

Например, сообщение об успешной инициализации:
<stream>
	<clientID>b52c96bea30646abf8170f333bbd42b9</clientID>
	<threadID>NeuroHopking</threadID>
	<message text="Initialization success" state="PROTO_INIT_OK" />
</stream>

Подробней о сообщениях см. "Сообщения"


//-----------------------------------------------------------------------------
                                    Сообщения
//-----------------------------------------------------------------------------

Признак успешной инициализации, а также другие сообщения, которые передаются
для подтверждения чего-либо или для указания ошибки, имеют такую структуру:

<stream>
	<clientID>b52c96bea30646abf8170f333bbd42b9</clientID>
	<threadID>NeuroHopking</threadID>
	<message text="Initialization success" state="PROTO_INIT_OK" />
</stream>

Атрибут text должен содержать человекочитаемое сообщение.
Атрибут state может быть следующим:

PROTO_INIT_OK			-	инициализация протокола успешна
PROTO_INIT_ERROR		-	инициализация протокола неуспешна
TRANS_BEGIN_OK			-	начало транзакции успешно
TRANS_BEGIN_ERROR		-	начало транзакции провалено
TRANS_END_OK			-	транзакция окончена успешно
TRANS_END_ERROR			-	транзакция окончена с ошибкой
TRANS_STOP				-	транзакция не состоится

Можно также определить пользовательские сообщения для обеспечения логики
уровня приложения.

Тег clientID должен содержать в себе MD5-хеш, который был изначально
передан при инициализации в теге uid.
Этот тег должен передаваться в дальнейшем во всех передаваемых потоках
для однозначной идентификации узлов.

Поскольку каждая задача будет выполняться в отдельном потоке, необходимо
знать, какой задаче предназначен поток.
Тег threadID содержит строковый идентификатор задачи, для которой
предназначается поток.


//-----------------------------------------------------------------------------
                                    Транзакции
//-----------------------------------------------------------------------------

При передаче больших массивов данных имеет смысл разбивать данные на части
(chunks). Протокол TCP разбивает информацию на пронумерованные пакеты. 
Далее с помощью протокола IP все пакеты передаются получателю, 
где они располагаются в нужном порядке и собираются в единое целое. 
То есть TCP/IP фактически разбивает данные на маленькие пакеты одинакового 
размера и автоматически определяет маршрут, по которому данные будут 
добираться до адресата.

Однако, для того, чтобы принять массив данных, необходимо знать величину 
этих данных в байтах, которую необходимо указать в параметре функции recv.

Транзакции разбивают процесс получения больших массивов данных на две части:

1) Происходит инициализация транзакции:
<stream>
	<clientID>b52c96bea30646abf8170f333bbd42b9</clientID>
	<threadID>NeuroHopking</threadID>
	<transaction state="TRANS_BEGIN" chunk-size="1024" />
</stream>

Атрибут state указывает на этап транзакции. Он может принимать несколько
значений:
TRANS_BEGIN				-	начало транзакции

Атрибут chunk-size должен содержать целочисленное значение величины
передаваемых данных в байтах. Обрамляющий XML также должен учитываться
при вычислении значения chunk-size. То есть chunk-size должен отражать
размер в байтах всего потока.

Ответ может быть таким:
<stream>
	<clientID>b52c96bea30646abf8170f333bbd42b9</clientID>
	<threadID>NeuroHopking</threadID>
	<message text="Transaction started" state="TRANS_BEGIN_OK" />
</stream>
Что означает, что отвечающая сторона готова принять данные.

Или таким:
<stream>
	<clientID>b52c96bea30646abf8170f333bbd42b9</clientID>
	<threadID>NeuroHopking</threadID>
	<message text="Can't receive data, i'm busy" state="TRANS_BEGIN_ERROR" />
</stream>
Что означает, что отвечающая сторона по какой-то причине не может
принять данные.

2) Передаются данные:
<stream>
	<clientID>b52c96bea30646abf8170f333bbd42b9</clientID>
	<threadID>NeuroHopking</threadID>
	<data>SGVsbG8gd29ybGQhISE=</data>
</stream>

Тег data должен содержать base64-хеш передаваемых данных. В нашем случае
была передана строка "Hello world!!!".

Ответ должен содержать сообщение об успехе либо провале при принятии данных:
<stream>
	<clientID>b52c96bea30646abf8170f333bbd42b9</clientID>
	<threadID>NeuroHopking</threadID>
	<message text="Data received sucessfull" state="TRANS_END_OK" />
</stream>

или
<stream>
	<clientID>b52c96bea30646abf8170f333bbd42b9</clientID>
	<threadID>NeuroHopking</threadID>
	<message text="Can't receive data" state="TRANS_END_ERROR" />
</stream>

Получив отрицательный ответ от принимающей стороны, можно попытаться 
передать данные повторно, либо отказаться от передачи, передав сообщение:
<stream>
	<clientID>b52c96bea30646abf8170f333bbd42b9</clientID>
	<threadID>NeuroHopking</threadID>
	<message text="I am stopping the transaction" state="TRANS_STOP" />
</stream>
В таком случае получаемая сторона может больше не ожидать данные и продолжить
работу по своему сценарию. Это сообщение может отправить только сторона,
отправляющая данные.


//-----------------------------------------------------------------------------