[Ace-users] [ace-users] PRF: Documenation not matching Code

[Steve Huston]

Hi Andre,

Thanks for raising this point. I've corrected the description of the
hook method (the code is, of course, correct ;-) as follows:

  /**
   * You can specify a hook function to event-handling methods that
will
   * be called after each iteration of event handling.  If the hook
function
   * returns a non-zero value, the event loop will immediately resume
   * waiting for the next event(s) to process without checking the
error
   * status of the just-completed iteration of event handling or the
   * end-of-loop indication. If the hook function returns 0, the event
   * handling error status and the end-of-loop indication will be
checked
   * as normal, just as if there is no hook function specified.
   */

If something is still unclear, please let me know.

Thanks,
-Steve

--
Steve Huston, Riverace Corporation
Want to take ACE training on YOUR schedule?
See http://www.riverace.com/training.htm

-----Original Message-----
From: ace-users-bounces at cse.wustl.edu
[mailto:ace-users-bounces at cse.wustl.edu] On Behalf Of Andre Kostur
Sent: Thursday, November 15, 2007 5:07 PM
To: ace-users at cs.wustl.edu
Subject: [ace-users] PRF: Documenation not matching Code


Truncated PRF:
 
    ACE VERSION: 5.6.1
 
    AREA/CLASS/EXAMPLE AFFECTED: Documentation/Implementation of
ACE_Reactor
 
    DOES THE PROBLEM AFFECT:
        COMPILATION? No
        LINKING? No
            On Unix systems, did you run make realclean first?
        EXECUTION? Yes
        OTHER (please specify)? No
 
    SYNOPSIS: The documentation of the REACTOR_EVENT_HOOK doesn't
match the implementation.
 
    DESCRIPTION:
 
The documentation for the REACTOR_EVENT_HOOK indicates: "If this
function returns 0, <run_reactor_event_loop> will check for the return
value of <handle_event>. If it is -1, the <run_reactor_event_loop>
will return (pre-maturely.)".  However if you examine the code (in
ACE_Reactor::run_reactor_event_loop):
 
  while (1)
    {
      int result = this->implementation_->handle_events ();
 
      if (eh != 0 && (*eh)(this))   
        continue;       
      else if (result == -1 && this->implementation_->deactivated ())
        return 0;
      else if (result == -1) 
        return -1;        
    }
 
This shows that if the eh returns 0, then the code flow is correct.
However if eh returns -1 (or any other non-zero value), this results
in the while loop continuing.
 
    SAMPLE FIX/WORKAROUND:
 
Replace the continue statement with a return statement.  I'm not sure
what would be appropriate to be returned: the return value from eh, or
result.
 
 
 
Regards,
 
Andre Kostur
Incognito Software Inc.
Senior Software Design Engineer
T: +1(604)678-2864
F: +1(604)688-4339
E: akostur at incognito.com
 
www.incognito.com
 
 
 
Regards,
 
Andre Kostur
Incognito Software Inc.
Senior Software Design Engineer
T: +1(604)678-2864
F: +1(604)688-4339
E: akostur at incognito.com
 
www.incognito.com