home *** CD-ROM | disk | FTP | other *** search
/ PC Active 2009 July/August / PC Active NR.227.iso / Software / Games / windows / Freeciv-2.1.9-win32-gtk2-setup.exe / doc / README.delta < prev    next >
Encoding:
Text File  |  2009-03-25  |  6.5 KB  |  148 lines
  1. =========================================================================
  2.   Delta
  3. =========================================================================
  4.  
  5. If delta is enable for this packet the packet-payload (after the 3
  6. byte packet-header) is followed by the delta-header. The delta-header
  7. is a bitvector which represents all non-key fields of the packet. If
  8. the the field has changed the corresponding bit is set and the field
  9. value is so included in delta-body. The values of the unchanged fields
  10. will be filled in from an old version at the receiving side.
  11.  
  12. For bool field another optimization called bool-header-folding is
  13. applied. Instead of sending an indicator in the bitvector if the given
  14. bool values has changed (and so using 1 byte for the real value) the
  15. actual value of the bool is transfered in the bitvector bit of this
  16. bool field.
  17.  
  18. Another optimization called array-diff is used to reduce the amount of
  19. elements transfered if an array is changed. This is independent of the
  20. delta-header bit i.e. it will only be used if the array has changed
  21. its value and the bit indicates this. Instead of transferring the
  22. whole array only a list of (index,new value of this index) pairs are
  23. transferred. The index is 8bit and the end of this pair list is
  24. denoted by an index of 255.
  25.  
  26. =========================================================================
  27.   Compression
  28. =========================================================================
  29.  
  30. To further reduce the network traffic the (delta) packets are
  31. compressed. To get better compression results multiple packets are
  32. grouped together and compressed into a chunk. This chunk is then
  33. transfered as a normal packet. A chunk packet start with the 2 byte
  34. length field which every packet has. A chunk packet has no type. A
  35. chunk packet is identified by having a too large length field. If the
  36. length of the packet is over COMPRESSION_BORDER it is a chunk
  37. packet. It will be uncompressed at the receiving side and re-feed into
  38. the receiving queue.
  39.  
  40. If the length of the chunk packet can't be expressed in the available
  41. space of the 16bit length field (>48kb) the chunk is sent as a jumbo
  42. packet. The difference between a normal chunk packet and a jumbo chunk
  43. packet is that the jumbo packet has JUMBO_SIZE in the size field and
  44. has an additional 4 byte len field after the 2 byte len field. The
  45. second len field contains the the size of the whole packet (2 byte
  46. first length field + 4 byte second length field + compressed data).
  47.  
  48. Packets are grouped for the compression based on the
  49. PACKET_PROCESSING_STARTED/PACKET_PROCESSING_FINISHED and
  50. PACKET_FREEZE_HINT/PACKET_THAW_HINT packet pairs. If the first
  51. (freeze) packet is encountered the packets till the second (thaw)
  52. packet are put into a queue. This queue is then compressed and sent as
  53. a chunk packet. If the compression would expand in size the queued
  54. packets are sent uncompressed as "normal" packets.
  55.  
  56. The compression level can be controlled by the
  57. FREECIV_COMPRESSION_LEVEL environment variable.
  58.  
  59. =========================================================================
  60.   Files
  61. =========================================================================
  62.  
  63. There are four file/filesets involved in the delta protocol:
  64.  1) the definition file (common/packets.def).
  65.  2) the generator (common/generate_packets.py).
  66.  3) the generated files (*/*_gen.[ch] or as a list
  67.  client/civclient_gen.c, client/packhand_gen.h, common/packets_gen.c,
  68.  common/packets_gen.h, server/hand_gen.h and server/srv_main_gen.c).
  69.  4) the overview (README.delta, this file)
  70.  
  71. The definition file lists all valid packet types with their
  72. fields. The generator takes this as input and creates the generated
  73. files.
  74.  
  75. For adding and/or removing packets and/or fields you only have to
  76. touch the definition file. If you however plan to change the generated
  77. code (adding more statistics for example) you have to change the
  78. generator.
  79.  
  80. =========================================================================
  81.   Changing the definition file
  82. =========================================================================
  83.  
  84. Adding a packet:
  85.  1) choose an unused packet number. The generator will make sure that
  86.  you don't use the same number two times.
  87.  2) choose a packet name. It should follow the naming style of the
  88.  other packets: PACKET_<group>_<remaining>. <group> may be SERVER,
  89.  CITY, UNIT, PLAYER, DIPLOMACY and so on.
  90.  3) decide if this packet goes from server to client or client to server
  91.  4) choose the field names and types
  92.  5) choose packet and field flags
  93.  6) write the entry into the corresponding section of common/packets.def
  94.  
  95. If you add a field which is a struct (say "foobar") you have to write
  96. the following functions: dio_get_foobar, dio_put_foobar and
  97. are_foobars_equal.
  98.  
  99. Removing a packet:
  100.  1) add a mandatory capability
  101.  2) remove the entry from common/packets.def
  102.  
  103. Adding a field:
  104.  Option A:
  105.    1) add a mandatory capability
  106.    2) add a normal field line:
  107.       COORD x
  108.  Option B:
  109.    1) add a non-mandatory capability (say "new_version")
  110.    2) add a normal field line containing this capability in an add-cap
  111.    flag:
  112.       COORD x; add-cap(new_version)
  113.  
  114. Removing a field:
  115.  Option A:
  116.    1) add a mandatory capability
  117.    2) remove the corresponding field line
  118.  Option B:
  119.    1) add a non-mandatory capability (say "cleanup")
  120.    2) add to the corresponding field line a remove-cap flag
  121.  
  122. After changing the definition file the generator has to be run. The
  123. common/Makefile will take care of this. You don't need to run
  124. autoconf/automake/configure.
  125.  
  126. =========================================================================
  127.   Capabilities and variants
  128. =========================================================================
  129.  
  130. The generator has to generate code which supports different
  131. capabilities at runtime according to the specification given in the
  132. definitions with add-cap and remove-cap. The generator will find the
  133. set of used capabilities for a given packet. Lets say there are two
  134. fields with "add-cap(cap1)" and one field with an "remove-cap(cap2)"
  135. flag. So the set of capabilities are cap1, cap2. At runtime the
  136. generated code may run under 4 different capabilities:
  137.  - neither cap1 nor cap2 are set
  138.  - cap1 is set but cap2 isn't
  139.  - cap1 is not set but cap2 is
  140.  - cap1 and cap2 are set
  141.  
  142. Each of these combinations is called a variant. If n is the number of
  143. capabilities used by the packet the number of variants is 2^n.
  144.  
  145. For each of these variant a seperate send and receive function will be
  146. generated. The variant for a packet and a connection are calculated
  147. once and then saved in the connection struct.
  148.