Java Question RaisesSynchronousEvents

Discussion in 'Libraries developers questions' started by Erel, Oct 2, 2013.

  1. Erel

    Erel Administrator Staff Member Licensed User

    @RaisesSynchronousEvents is a new annotation added in B4A v3.0. It is only relevant for the rapid debugger.

    This annotation tells the debugger engine that the method tagged with this annotation can raise one or more events as a direct result of the call (before the method returns).

    In most cases it is not needed. In the official libraries it was only* required in XmlSax library.
    Calling SaxParser.Parse or SaxParser.Parse2 causes the XML events to be raised. The method returns only after it calls these events.

    * This annotation is also required when showing modal dialogs (Msgbox, Msgbox2,...).

    The updated doclet tool is available here: http://www.basic4ppc.com/android/fo...-build-libraries-without-eclipse.29918/page-3
     
  2. Erel

    Erel Administrator Staff Member Licensed User

    More information about this annotation.

    The rapid debugger is made of two components: debugger engine and device shell app. The code is executed by the debugger engine (which runs on the desktop). The debugger engine sends commands to the shell app. The result is the same as running the code directly on the device.

    To avoid network latency the debugger engine doesn't wait for the result of each method. It sends a large chunk of commands and only when it must it waits for a result.

    If however an event is raised directly from a call to another method then the debugger engine must wait for the result or else the buffers state will be broken.

    For example, consider this code:
    Code:
    'Class module
    Sub Class_Globals

    End Sub

    'Initializes the object. You can add parameters to this method if needed.
    Sub Initialize

    End Sub

    Sub SubThatCanRaiseEvent (target As Object, i As Int)
       
    If i = 3 Then
         
    CallSub(target, "test")
       
    End If
    End Sub
    CallSub method is marked with @RaisesSynchronousEvents so the engine knows that it can raise an event and it will be ready for it.

    If however you compile this code into a library and run it, you will get an error message saying:
    The program will then crash.

    The engine doesn't know that the method SubThatCanRaiseEvent can raise an event so when the event is raised it corrupts the buffers.

    The solution for Java libraries is to add the @RaisesSynchronousEvents annotation on those methods.
    For B4A compiled libraries you should use the new RaisesSynchronousEvents attribute:
    Code:
    'Class module
    #RaisesSynchronousEvents: SubThatCanRaiseEvent
    Sub Class_Globals

    End Sub

    'Initializes the object. You can add parameters to this method if needed.
    Sub Initialize

    End Sub

    Sub SubThatCanRaiseEvent (target As Object, i As Int)
       
    If i = 3 Then
         
    CallSub(target, "test")
       
    End If
    End Sub
    Note that you can add this attribute multiple times, for each of the relevant subs.
     
  3. Erel

    Erel Administrator Staff Member Licensed User

    As it will take some time for library developers to update their libraries, a workaround is provided.

    The file LibrariesExceptions.txt which is located in Basic4android folder lists methods that should have been marked with this annotation. The IDE reads this file when libraries are loaded. This way the current libraries can continue to work properly (it is exactly the same as adding the annotation).

    As of beta #6, the file content is:
    The syntax is (case sensitive):
    1: <short name>.<method name>
     
  4. Rusty

    Rusty Well-Known Member Licensed User

    I'm using the UltimateListView in my MAIN.
    How do I specify the #RaisesSynchronousEvents: SubThatCanRaiseEvent within the MAIN (i.e. not within a library)?
    Only a problem with Rapid Debugger...
    Thanks,
    Rusty
     
  5. Erel

    Erel Administrator Staff Member Licensed User

    The library author should do it. If it is a specific method then you can edit the xml file and add RaisesSynchronousEvents="true" to the name element. See XmlSax.xml for an example.
     
    Rusty likes this.
  6. corwin42

    corwin42 Expert Licensed User

    Is the @RaisesSynchronousEvents annotation still required?

    I want to update the AHViewPager library and checked the events.

    The ViewPager_PageScrolled event is raised with raiseEvent() because this event has to be fired as fast as possible so if you implement a page change indicator with this event you can animate it smooth.

    Is AHViewPager.GotoPage in the exceptions list because of the modal dialogs problem?

    I currently don't use the @RaisesSynchronousEvents annotation for AHViewPager but a test app runs without problems with the rapid debugger. Maybe that is because I do only some log output in the PageScrolled event sub. So it is not required that the debugger waits for the event to finish. Or do I only need to use the annotation if the library uses the result of raiseEvent()?

    In AHSwipeToRefresh library there is an event (STR_CanChildScrollUp) which returns true or false so the library can check if it should start the refresh action or not. This of course needs to be called synchronous because the library needs the feedback. But where should I put the annotation? There is no method which raises the event. It is a gesture the user starts on the display (swiping down).

    For me it is still not very clear where and when to use this annotation.
     
  7. Erel

    Erel Administrator Staff Member Licensed User

    Yes.

    In most cases nothing bad will happen if you don't add this annotation. The event will only fire after the current code completes. You can think of it as if the debugger changed a CallSub to CallSubDelayed.

    Yes.

    You can call raiseEvent without this annotation. The annotation is only required if the raiseEvent is called as a result of another method call.
    The logs will tell you if there is a missing annotation.
     
  8. Computersmith64

    Computersmith64 Well-Known Member Licensed User

    I'm seeing this:

    when testing using the rapid debugger. If I understand the previous posts correctly, this won't cause any issues in the release build?

    - Colin.
     
  9. corwin42

    corwin42 Expert Licensed User

    Ok, but if I understand correctly because AHViewPager uses raiseEventFromUI() in the latest versions it is no longer required?

    Thanks for the info. I think I understand it now.

    Seems that I have to use the rapid debugger more often for testing my libraries.
     
  10. Erel

    Erel Administrator Staff Member Licensed User

    That is correct.

    Yes. RaisesSynchronousEvents and this warning message are only relevant to debug (rapid) mode.
     
Loading...