docs/mono_handle_d

   1 =pod
   2
   3 =head1 Internal design document for the mono_handle_d
   4
   5 This document is designed to hold the design of the mono_handle_d and
   6 not as an api reference.
   7
   8 =head2 Primary goal and purpose
   9
  10 The mono_handle_d is a process which takes care of the (de)allocation
  11 of scratch shared memory and handles (of files, threads, mutexes,
  12 sockets etc. see L<WapiHandleType>) and refcounts of the
  13 filehandles. It is designed to be run by a user and to be fast, thus
  14 minimal error checking on input is done and will most likely crash if
  15 given a faulty package. No effort has been, or should be, made to have
  16 the daemon talking to machine of different endianness/size of int.
  17
  18 =head2 How to start the daemon
  19
  20 To start the daemon you either run the mono_handle_d executable or try
  21 to attach to the shared memory segment via L<_wapi_shm_attach> which
  22 will start a daemon if one does not exist.
  23
  24 =head1 Internal details
  25
  26 The daemon works by opening a socket and listening to clients. These
  27 clients send packages over the socket complying to L<struct
  28 WapiHandleRequest>.
  29
  30 =head2 Possible requests
  31
  32 =over
  33
  34 =item WapiHandleRequest_New
  35
  36 Find a handle in the shared memory segment that is free and allocate
  37 it to the specified type. To destroy use
  38 L</WapiHandleRequest_Close>. A L<WapiHandleResponse> with
  39 .type=WapiHandleResponseType_New will be sent back with .u.new.handle
  40 set to the handle that was allocated. .u.new.type is the type that was
  41 requested.
  42
  43 =item WapiHandleRequestType_Open
  44
  45 Increase the ref count of an already created handle. A
  46 L<WapiHandleResponse> with .type=WapiHandleResponseType_Open will be sent
  47 back with .u.new.handle set to the handle, .u.new.type is set to the
  48 type of handle this is.
  49
  50 =item WapiHandleRequestType_Close
  51
  52 Decrease the ref count of an already created handle. A
  53 L<WapiHandleResponse> with .type=WapiHandleResponseType_Close will be
  54 sent back with .u.close.destroy set to TRUE if ref count for this
  55 client reached 0.
  56
  57 =item WapiHandleRequestType_Scratch
  58
  59 Allocate a shared memory area of size .u.scratch.length in bytes. A
  60 L<WapiHandleResponse> with .type=WapiHandleResponseType_Scratch will be
  61 sent back with .u.scratch.idx set to the index into the shared
  62 memory's scratch area where to memory begins. (works just like
  63 malloc(3))
  64
  65 =item WapiHandleRequestType_Scratch
  66
  67 Deallocate a shared memory area, this must have been allocated before
  68 deallocating. A L<WapiHandleResponse> with
  69 .type=WapiHandleResponseType_ScratchFree will be sent back (works just
  70 like free(3))
  71
  72 =back
  73
  74 =head1 Why a daemon
  75
  76 From an email:
  77
  78 Dennis: I just have one question about the daemon... Why does it
  79 exist? Isn't it better performancewise to just protect the shared area
  80 with a mutex when allocation a new handle/shared mem segment or
  81 changing refcnt? It will however be a less resilient to clients that
  82 crash (the deamon cleans up ref'd handles if socket closes)
  83
  84 Dick: It's precisely because with a mutex the shared memory segment
  85 can be left in a locked state. Also, it's not so easy to clean up
  86 shared memory without it (you can't just mark it deleted when creating
  87 it, because you can't attach any more readers to the same segment
  88 after that).  I did some minimal performance testing, and I don't
  89 think the daemon is particularly slow.
  90
  91
  92 =head1 Authors
  93
  94 Documentaion: Dennis Haney
  95
  96 Implementation: Dick Porter
  97
  98 =cut