<commit_before>RFC 0065: Server Socket Reader API
========================================================================
$Id$

@authors: friebe, gelli
@created: Wed Jul  5 17:28:01 CEST 2006
@status: draft
@category: peer.server

Scope of Change
---------------
Reading the data off an accept()'ed socket in the server APIs will be made
overrideable by supplying a reader implementation.


Rationale
---------
Performance improvement and flexibility.


Functionality
-------------

Server implementation changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following code in the three server implementations:
<?php
  $m= &$socket->accept();
  // ...
  $data= $m->readBinary();
?>
will be replaced by
<?php
  $m= &$socket->accept();
  // ...
  $data= $this->reader->readFrom($m);
?>

Note: The default behaviour (readBinary()) will be kept by a new class.

Example
~~~~~~~

Implementing a reader:
<?php
  class EascReader extends Object {

    function readBytes(&$sock, $num) {
      $return= '';
      while (strlen($return) < $num) {
        if (0 == strlen($buf= $sock->readBinary($num - strlen($return)))) return;
        $return.= $buf;
      }
      return $return;
    }
  
    function readFrom(&$sock) {
      $header= unpack(
        'Nmagic/cvmajor/cvminor/ctype/ctran/Nlength', 
        $this->readBytes($sock, 12)
      );

      // ... abbreviated ...

      return ServerDelegate::delegateFor($header['type'], $sock);
    }

  } implements(__FILE__, 'peer.server.ServerDataReader');
?>

Setting the reader implementation:
<?php
  with ($server= &new Server($argv[1], 6448)); {
    $server->setReader(new EascReader());
    $server->addListener(new RemoteInvocationListener());
    $server->init();
    $server->service();
    $server->shutdown();
  }
?>


Security considerations
-----------------------
n/a


Speed impact
------------
Minimalistic.


Dependencies
------------
- New Reader interface.
- New Reader default behaviour implementation


Related documents
-----------------
n/a


Comments
--------
- friebe, Fri Jul  7 11:26:16 CEST 2006
  Not sure about the name of this reader. SocketReader seems a bit too
  generic. ServerDataReader? And with dataFrom() or readDataFrom() 
  instead of readData()?

- gelli, Fri Jul  7 11:58:40 CEST 2006
  As of the current state, which is that this new api will always read from
  sockets, i think SocketReader as interface name is not too generic but 
  ServerDataReader is. Addressing the methods name i'd prefer readFrom($socket)
  as it's literally a little bit more "readable"

  
<EOF><commit_msg>- Add some more thoughts on naming<commit_after>RFC 0065: Server Socket Reader API
========================================================================
$Id$

@authors: friebe, gelli
@created: Wed Jul  5 17:28:01 CEST 2006
@status: draft
@category: peer.server

Scope of Change
---------------
Reading the data off an accept()'ed socket in the server APIs will be made
overrideable by supplying a reader implementation.


Rationale
---------
Performance improvement and flexibility.


Functionality
-------------

Server implementation changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following code in the three server implementations:
<?php
  $m= &$socket->accept();
  // ...
  $data= $m->readBinary();
?>
will be replaced by
<?php
  $m= &$socket->accept();
  // ...
  $data= $this->reader->readFrom($m);
?>

Note: The default behaviour (readBinary()) will be kept by a new class.

Example
~~~~~~~

Implementing a reader:
<?php
  class EascReader extends Object {

    function readBytes(&$sock, $num) {
      $return= '';
      while (strlen($return) < $num) {
        if (0 == strlen($buf= $sock->readBinary($num - strlen($return)))) return;
        $return.= $buf;
      }
      return $return;
    }
  
    function readFrom(&$sock) {
      $header= unpack(
        'Nmagic/cvmajor/cvminor/ctype/ctran/Nlength', 
        $this->readBytes($sock, 12)
      );

      // ... abbreviated ...

      return ServerDelegate::delegateFor($header['type'], $sock);
    }

  } implements(__FILE__, 'peer.server.ServerDataReader');
?>

Setting the reader implementation:
<?php
  with ($server= &new Server($argv[1], 6448)); {
    $server->setReader(new EascReader());
    $server->addListener(new RemoteInvocationListener());
    $server->init();
    $server->service();
    $server->shutdown();
  }
?>


Security considerations
-----------------------
n/a


Speed impact
------------
Minimalistic.


Dependencies
------------
- New Reader interface.
- New Reader default behaviour implementation


Related documents
-----------------
n/a


Comments
--------
- friebe, Fri Jul  7 11:26:16 CEST 2006
  Not sure about the name of this reader. SocketReader seems a bit too
  generic. ServerDataReader? And with dataFrom() or readDataFrom() 
  instead of readData()?

- gelli, Fri Jul  7 11:58:40 CEST 2006
  As of the current state, which is that this new api will always read from
  sockets, i think SocketReader as interface name is not too generic but 
  ServerDataReader is. Addressing the methods name i'd prefer readFrom($socket)
  as it's literally a little bit more "readable"

- friebe, Sun Jul  9 10:11:24     2006
  More thoughts on naming:
  * Reads data from client => ClientDataReader::readFrom($sock)  
  * Extracts data from socket => DataExtractor::dataFrom($sock)
  * Interprets data from socket => DataInterpreter::dataFrom($sock)
  * Implements reading => (Server)(Data)Read(ing|er)Implementation::readFrom($sock)

<EOF>
{'fraction_non_alphanumeric': 0.19045015491160927, 'fraction_numerical': 0.018407144158921085, 'mean_word_length': 3.1170292573143286, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 41, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1254435', 'n_tokens_mistral': 1707, 'n_tokens_neox': 1542, 'n_words': 521}