libatalk/dsi/README

   1 SIGNALS AND WRITES TO CLIENT:
   2 because AFP/TCP uses a streaming protocol, we need to make sure that
   3 writes to the client are atomic. notably, signal handlers which write
   4 data can't interrupt data currently being written. in addition, some
   5 functions get called from the signal handlers or can write partial
   6 packets. we need to SIG_BLOCK/SIG_SETMASK those functions instead of
   7 SIG_BLOCK/SIG_UNBLOCK'ing them. furthermore, certain functions which
   8 write to the client can get called at any time. to avoid corruption,
   9 we need to make sure that these functions DO NOT touch any common-use
  10 buffers.
  11
  12 signals that send data to the client and should block other signals
  13 (afp_dsi.c):
  14         SIGALRM (tickle handler)
  15         SIGHUP (attention)
  16         SIGTERM (attention)
  17
  18 functions which need SIG_BLOCK/SIG_SETMASK: dsi_send, dsi_attention
  19 functions which can use SIG_BLOCK/SIG_UNBLOCK: dsi_read
  20
  21 functions which need their own buffers: dsi_attention, dsi_tickle
  22
  23
  24 PERFORMANCE TWEAKING:
  25 sending complete packets or the header and a partial packet to the
  26 client should always be handled by proto_send. for dsi_tcp.c,
  27 proto_send will coalesce the header and data by using writev.
  28 in addition, appleshare sessions often involve
  29 the sending and receiving of many small packets. as a consequence, i
  30 use TCP_NODELAY to speed up the turnaround time.
  31
  32 because dsi_read can send incomplete packets, proto_send should not
  33 use the length parameter to specify the dsi_len field in the
  34 header. instead, anything that uses proto_send needs to specify
  35 dsi_len (in network byte order) before calling proto_send. the
  36 dsi_send() macro already does this.
  37
  38 functions that need to specify .dsi_len: dsi_readinit, dsi_cmdreply
  39
  40 mmap doesn't actually help things that much, so i don't use it.
  41
  42 to reduce the amount of tickles generated on a slow link, i actually
  43 turn off SIGALRM for the duration of a "known" large file transfer
  44 (i.e., dsi_read/write).
  45