thekid/rfc — Issue #90: RFC 0090: Refactor remote.protocol.Serializer
Author: thekid
Created: 2011-10-09 14:59:58+00:00
State: open

Scope of Change
====
The Serializer class' valueOf() method's signature will be changed.

Rationale
====
First of all, the current code *inside* valueOf() (and the SerializerMapping
implementations) consists of numerous repetitions which makes it hard to
read, debug and maintain. Second, exposing the &length member to "public"
space create ugly code there ($serializer->valueOf($data, $length= 0)). Third,
references to primitives will not work in the XP language.

Functionality
====

1) The SerializedData API
----

```php

```

2) Public API
----
Current Serializer::valueOf() signature:

```php

```

New Serializer::valueOf() signature:

```php

```

Example of new public API (unserializing a PersonReference object):

```php
valueOf(new SerializedData(
'O:15:"PersonReference":1:{s:2:"id";i:1549;}'
));
?>
```

3) API changes for SerializerMappings
----
Current SerializerMapping::valueOf() signature:

```php

```

New Serializer::valueOf() signature:

```php

```

4) Internal changes
----
All the substr() / $length++ / $offset+= $len calls can be replaced by
SerializedData() methods (as shown above).

Example (from theDateMapping class):

```php
consumeWord());
return $value;
}
?>
```

Security considerations
====
n/a

Speed impact
====
Running all tests from remote.ini yields almost the same time period
for both the old and the new implementations. On one machine I tested
the new implementation is about one tenth of a millisecond slower on
average for unserializing a simple object than the old one, but uses
about 20k less memory.

Test script for the old API
----

```php
valueOf($data, &$length= 0);
}
var_dump(memory_get_usage());
?>
```

Test script for the new API
----

```php
valueOf($data);
$data->offset= 0;
}
var_dump(memory_get_usage());
?>
```

Results
----
The test scripts were each run 20 times, using the "time" utility to
measure their runtime.

```
Which Average execution time Per loop run
----- ---------------------- -----------------------
Old 5.452 seconds 0.5452 milliseconds
New 6.567 seconds 0.6567 milliseconds

```

That makes a difference of 0.1115 milliseconds per loop execution. Not
really much...

Dependencies
====
New class: remote.protocol.SerializedData

Related documents
====
- http://xp-framework.net/rfc/contrib/rfc0090.diff
Patch implementing this RFC

Comments
====
n/a