home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Archived / Internet / News-Email / popstr202a / SockWatch / !ReadMe next >
Text File  |  1998-08-27  |  4KB  |  127 lines
  1. Document v0.06.  (C) Dickon Hood, see licence for details of copying etc.
  2.  
  3. To build, you'll need <ftp://ftp.fluff.org/pub/dickon/libs.zip> and BAX
  4. (available from somewhere under <http://www.doggysoft.co.uk/>).
  5.  
  6.  
  7. SocketWatch
  8. ===========
  9.  
  10. SocketWatch is a simple module designed to reduce the requirement of Wimp
  11. applications using sockets to constantly poll them using Null Wimp polls for
  12. data.
  13.  
  14. If you're not a programmer, stop reading now, this will probably make little
  15. sense to you.  If you are a programmer, but don't write networking
  16. applications, again, this is unlikely to be of interest.
  17.  
  18.  
  19. Rationale
  20. ---------
  21.  
  22. At boot time, my machine loads and runs five seperate applications which
  23. require open sockets.  As none of these have support modules associated with
  24. them, I'm assuming that they are constantly polling the sockets they open on
  25. null polls.  This is inefficient.
  26.  
  27. Sockets can be marked as asynchronous.  If they are, an Internet event (19)
  28. is generated whenever something interesting happens to them.  Events are only
  29. accessable to modules, however, and are useless in a Wimp environment.  The
  30. answer is to write a module which does that and notifies the parent
  31. application that something has happened.  If every application did this,
  32. there'd be another five or six modules running on my machine, all doing much
  33. the same job, which I don't need.
  34.  
  35. This attempts to address the issue by implementing a module with an open
  36. interface, and one which is generic enough to be applicable to almost every
  37. app. which could want to use it.
  38.  
  39.  
  40. Usage
  41. -----
  42.  
  43. SocketWatch relies upon a feature of Risc OS 3.1 and upwards, so won't work
  44. on ROS2.  Sorry, but there we go.
  45.  
  46. Sockets are registered with the module.  At this point, the socket is marked
  47. as asynchronous (so the parent app. doesn't need to).  A pollword and bit
  48. number to set are also supplied.
  49.  
  50. As some internal structure has to be created, a pollword of 0 is acceptable,
  51. and, if passed, the module will use one of the words in this structure as the
  52. pollword.  This is returned to the app. in r0.
  53.  
  54. When an Internet event is triggered, the module scans all registered sockets. 
  55. If one is matched, the appropriate bit is set in the pollword.  This allows
  56. other bits to be reserved for other things.  Note, it is not an error for a
  57. socket to have multiple pollwords associated with it; there is no reason I
  58. can think of for two apps. to share one socket (*why* is another matter, but
  59. it shouldn't be an error); these may both register PWs for them.
  60.  
  61.  
  62. SWIs
  63. ----
  64.  
  65. SWI SocketWatch_Register (0x52280)
  66.  
  67. On entry: r0 => pollword, 0 for module to allocate one,
  68.           r1 =  bitmask to set if there's activity
  69.           r2 =  socket number.
  70.  
  71. On exit:  r0 => pollword.
  72.  
  73. If the pollword passed is 0, one allocated from the internal structure will
  74. be returned.  Note that this is freed when at the time of deregistering and
  75. may not be used afterwards.
  76.  
  77.  
  78.  
  79. SWI SocketWatch_Deregister (0x52281)
  80.  
  81. On entry: r0 =  socket,
  82.           r1 => pollword.
  83.  
  84. On exit:  all preserved.
  85.  
  86. The socket is no longer watched.  If the pollword was allocated by the
  87. module, it is not valid once this call is called.
  88.  
  89.  
  90.  
  91. SWI SocketWatch_AtomicReset (0x52282)
  92.  
  93. On entry: r0 => pollword
  94.           r1 =  new value
  95.  
  96. On exit:  r0 =  old value
  97.           r1 preserved.
  98.  
  99. This SWI reads from r0, writes r1 to r0, then exits, all with IRQs off,
  100. making it an atomic operation (ie., one which may not be interrupted).  It is
  101. a problem with Pollwords in that they're used by IRQ or Callback code, yet
  102. read and reset by usermode code which can't disable IRQs easily.  This
  103. removes the problem where the app. reads the PW, IRQ routine sets a couple of
  104. bits, then the forground resets it.
  105.  
  106.  
  107.  
  108. SWI SocketWatch_AllocPW (0x52283)
  109.  
  110. On entry: -
  111.  
  112. On exit:  r0 => 4 bytes of RAM which may be released by SWI
  113. SocketWatch_DeallocPW.
  114.  
  115. ATM, this SWI claims four bytes of RMA; this isn't efficient, and may be
  116. changed in later releases.  The SWI is provided for convenience's sake.
  117.  
  118.  
  119.  
  120. SWI SocketWatch_DeallocPW (0x52284)
  121.  
  122. On entry: r0 => pollword, as allocated by SWI SocketWatch_AllocPW.
  123.  
  124. On exit:  all preserved.
  125.  
  126. ATM this calls OS_Module 7 to free the word.
  127.