home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.3 / Async.3 < prev    next >
Encoding:
Text File  |  1995-07-26  |  11.9 KB  |  199 lines
  1.  
  2.  
  3.  
  4.      TTTTccccllll____AAAAssssyyyynnnnccccCCCCrrrreeeeaaaatttteeee((((3333))))          TTTTccccllll ((((7777....0000))))          TTTTccccllll____AAAAssssyyyynnnnccccCCCCrrrreeeeaaaatttteeee((((3333))))
  5.  
  6.  
  7.  
  8.      _________________________________________________________________
  9.  
  10.      NNNNAAAAMMMMEEEE
  11.           Tcl_AsyncCreate,       Tcl_AsyncMark,       Tcl_AsyncInvoke,
  12.           Tcl_AsyncDelete - handle asynchronous events
  13.  
  14.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.           ####iiiinnnncccclllluuuuddddeeee <<<<ttttccccllll....hhhh>>>>
  16.  
  17.           extern int ttttccccllll____AAAAssssyyyynnnnccccRRRReeeeaaaaddddyyyy;
  18.  
  19.           Tcl_AsyncHandler
  20.           TTTTccccllll____AAAAssssyyyynnnnccccCCCCrrrreeeeaaaatttteeee(_p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  21.  
  22.           TTTTccccllll____AAAAssssyyyynnnnccccMMMMaaaarrrrkkkk(_a_s_y_n_c)
  23.  
  24.           int
  25.           TTTTccccllll____AAAAssssyyyynnnnccccIIIInnnnvvvvooookkkkeeee(_i_n_t_e_r_p, _c_o_d_e)
  26.  
  27.           TTTTccccllll____AAAAssssyyyynnnnccccDDDDeeeelllleeeetttteeee(_a_s_y_n_c)
  28.  
  29.      AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  30.           Tcl_AsyncProc      *_p_r_o_c        (in)      Procedure       to
  31.                                                     invoke  to  handle
  32.                                                     an    asynchronous
  33.                                                     event.
  34.  
  35.           ClientData         _c_l_i_e_n_t_D_a_t_a   (in)      One-word value  to
  36.                                                     pass to _p_r_o_c.
  37.  
  38.           Tcl_AsyncHandler   _a_s_y_n_c        (in)      Token          for
  39.                                                     asynchronous event
  40.                                                     handler.
  41.  
  42.           Tcl_Interp         *_i_n_t_e_r_p      (in)      Tcl interpreter in
  43.                                                     which  command was
  44.                                                     being    evaluated
  45.                                                     when  handler  was
  46.                                                     invoked,  or  NULL
  47.                                                     if   handler   was
  48.                                                     invoked when there
  49.                                                     was no interpreter
  50.                                                     active.
  51.  
  52.           int                _c_o_d_e         (in)      Completion    code
  53.                                                     from  command that
  54.                                                     just completed  in
  55.                                                     _i_n_t_e_r_p,  or  0  if
  56.                                                     _i_n_t_e_r_p is NULL.
  57.      _________________________________________________________________
  58.  
  59.  
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 7/10/95)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      TTTTccccllll____AAAAssssyyyynnnnccccCCCCrrrreeeeaaaatttteeee((((3333))))          TTTTccccllll ((((7777....0000))))          TTTTccccllll____AAAAssssyyyynnnnccccCCCCrrrreeeeaaaatttteeee((((3333))))
  71.  
  72.  
  73.  
  74.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  75.           These procedures provide a safe mechanism for  dealing  with
  76.           asynchronous  events such as signals.  If an event such as a
  77.           signal occurs while a Tcl script is being evaluated then  it
  78.           isn't  safe  to  take  any substantive action to process the
  79.           event.  For example, it isn't safe to evaluate a Tcl  script
  80.           since  the  intepreter  may  already  be  in  the  middle of
  81.           evaluating a script; it may not even  be  safe  to  allocate
  82.           memory,  since  a  memory  allocation  could  have  been  in
  83.           progress when the event occurred.  The only safe approach is
  84.           to  set  a  flag  indicating  that  the event occurred, then
  85.           handle the event later when the  world  has  returned  to  a
  86.           clean   state,   such  as  after  the  current  Tcl  command
  87.           completes.
  88.  
  89.           TTTTccccllll____AAAAssssyyyynnnnccccCCCCrrrreeeeaaaatttteeee creates an asynchronous handler and  returns
  90.           a  token  for  it.  The asynchronous handler must be created
  91.           before any occurrences of the asynchronous event that it  is
  92.           intended  to  handle  (it is not safe to create a handler at
  93.           the time of an event).  When an  asynchronous  event  occurs
  94.           the  code  that detects the event (such as a signal handler)
  95.           should call TTTTccccllll____AAAAssssyyyynnnnccccMMMMaaaarrrrkkkk with the token  for  the  handler.
  96.           TTTTccccllll____AAAAssssyyyynnnnccccMMMMaaaarrrrkkkk will mark the handler as ready to execute, but
  97.           it will not invoke the handler immediately.  Tcl  will  call
  98.           the  _p_r_o_c  associated with the handler later, when the world
  99.           is in a safe state, and _p_r_o_c can then carry out the  actions
  100.           associated  with  the  asynchronous event.  _P_r_o_c should have
  101.           arguments and result that match the type TTTTccccllll____AAAAssssyyyynnnnccccPPPPrrrroooocccc:
  102.                typedef int Tcl_AsyncProc(
  103.                     ClientData _c_l_i_e_n_t_D_a_t_a,
  104.                     Tcl_Interp *_i_n_t_e_r_p,
  105.                     int _c_o_d_e);
  106.           The _c_l_i_e_n_t_D_a_t_a will be the same as the  _c_l_i_e_n_t_D_a_t_a  argument
  107.           passed  to TTTTccccllll____AAAAssssyyyynnnnccccCCCCrrrreeeeaaaatttteeee when the handler was created.  If
  108.           _p_r_o_c is invoked just after a command has completed execution
  109.           in an interpreter, then _i_n_t_e_r_p will identify the interpreter
  110.           in which the command was evaluated  and  _c_o_d_e  will  be  the
  111.           completion  code  returned  by  that command.  The command's
  112.           result  will  be  present  in  _i_n_t_e_r_p->_r_e_s_u_l_t.   When   _p_r_o_c
  113.           returns,  whatever  it  leaves  in  _i_n_t_e_r_p->_r_e_s_u_l_t  will  be
  114.           returned as the result of the command and the integer  value
  115.           returned by _p_r_o_c will be used as the new completion code for
  116.           the command.
  117.  
  118.           It  is  also  possible  for  _p_r_o_c  to  be  invoked  when  no
  119.           interpreter  is active.  This can happen, for example, if an
  120.           asynchronous event occurs while the application  is  waiting
  121.           for  interactive  input  or an X event.  In this case _i_n_t_e_r_p
  122.           will be NULL and _c_o_d_e will be 0, and the return  value  from
  123.           _p_r_o_c will be ignored.
  124.  
  125.           The procedure TTTTccccllll____AAAAssssyyyynnnnccccIIIInnnnvvvvooookkkkeeee is called to invoke all of the
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 7/10/95)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      TTTTccccllll____AAAAssssyyyynnnnccccCCCCrrrreeeeaaaatttteeee((((3333))))          TTTTccccllll ((((7777....0000))))          TTTTccccllll____AAAAssssyyyynnnnccccCCCCrrrreeeeaaaatttteeee((((3333))))
  137.  
  138.  
  139.  
  140.           handlers that are ready.  The global variable ttttccccllll____AAAAssssyyyynnnnccccRRRReeeeaaaaddddyyyy
  141.           will be non-zero  whenever  any  asynchronous  handlers  are
  142.           ready;   it can be checked to avoid calls to TTTTccccllll____AAAAssssyyyynnnnccccIIIInnnnvvvvooookkkkeeee
  143.           when there are no ready handlers.  Tcl checks ttttccccllll____AAAAssssyyyynnnnccccRRRReeeeaaaaddddyyyy
  144.           after each command is evaluated and calls TTTTccccllll____AAAAssssyyyynnnnccccIIIInnnnvvvvooookkkkeeee if
  145.           needed.   Applications  may  also  call  TTTTccccllll____AAAAssssyyyynnnnccccIIIInnnnvvvvooookkkkeeee  at
  146.           interesting  times  for that application.  For example, Tk's
  147.           event handler checks ttttccccllll____AAAAssssyyyynnnnccccRRRReeeeaaaaddddyyyy  after  each  event  and
  148.           calls  TTTTccccllll____AAAAssssyyyynnnnccccIIIInnnnvvvvooookkkkeeee  if  needed.   The  _i_n_t_e_r_p  and  _c_o_d_e
  149.           arguments to TTTTccccllll____AAAAssssyyyynnnnccccIIIInnnnvvvvooookkkkeeee have the same  meaning  as  for
  150.           _p_r_o_c:   they identify the active intepreter, if any, and the
  151.           completion code from the command that just completed.
  152.  
  153.           TTTTccccllll____AAAAssssyyyynnnnccccDDDDeeeelllleeeetttteeee removes an asynchronous handler so that  its
  154.           _p_r_o_c  will never be invoked again.  A handler can be deleted
  155.           even when ready, and it will still not be invoked.
  156.  
  157.           If multiple handlers become active at  the  same  time,  the
  158.           handlers  are invoked in the order they were created (oldest
  159.           handler first).   The  _c_o_d_e  and  _i_n_t_e_r_p->_r_e_s_u_l_t  for  later
  160.           handlers reflect the values returned by earlier handlers, so
  161.           that the most recently created handler has  last  say  about
  162.           the  interpreter's  result  and  completion  code.   If  new
  163.           handlers  become  ready  while   handlers   are   executing,
  164.           TTTTccccllll____AAAAssssyyyynnnnccccIIIInnnnvvvvooookkkkeeee  will  invoke  them  all;   at each point it
  165.           invokes  the  highest-priority   (oldest)   ready   handler,
  166.           repeating  this  over and over until there are no longer any
  167.           ready handlers.
  168.  
  169.  
  170.      WWWWAAAARRRRNNNNIIIINNNNGGGG
  171.           It is almost always a bad idea  for  an  asynchronous  event
  172.           handler  to modify _i_n_t_e_r_p->_r_e_s_u_l_t or return a code different
  173.           from its _c_o_d_e argument.  This sort of behavior  can  disrupt
  174.           the  execution  of scripts in subtle ways and result in bugs
  175.           that  are  extremely  difficult  to  track  down.    If   an
  176.           asynchronous  event  handler  needs  to evaluate Tcl scripts
  177.           then it should first save _i_n_t_e_r_p->_r_e_s_u_l_t plus the values  of
  178.           the variables eeeerrrrrrrroooorrrrIIIInnnnffffoooo and eeeerrrrrrrroooorrrrCCCCooooddddeeee (this can be done, for
  179.           example, by storing them  in  dynamic  strings).   When  the
  180.           asynchronous  handler  is finished it should restore _i_n_t_e_r_p-
  181.           >_r_e_s_u_l_t, eeeerrrrrrrroooorrrrIIIInnnnffffoooo,  and  eeeerrrrrrrroooorrrrCCCCooooddddeeee,  and  return  the  _c_o_d_e
  182.           argument.
  183.  
  184.  
  185.      KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  186.           asynchronous event, handler, signal
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 7/10/95)
  196.  
  197.  
  198.  
  199.