B4J Tutorial [B4X] Resumable Subs - Sleep / Wait For

New video tutorial:


Resumable subs is a new feature added in B4J v5.50 / B4i v4.00 / B4A v7.00. It dramatically simplifies the handling of asynchronous tasks.
(This feature is a variant of stackless coroutines.)

The special feature of resumable subs is that they can be paused, without pausing the executing thread, and later be resumed.
The program doesn't wait for the resumable sub to be continued. Other events will be raised as usual.

Any sub with one or more calls to Sleep or Wait For is a resumable subs. The IDE shows an indicator next to the sub declaration:

Sleep

Using Sleep is simple:

Log(1)
Sleep(1000)
Log(2)

The sub will be paused for 1000 milliseconds and then be resumed.

You can call Sleep(0) for the shortest pause. This can be used to allow the UI to be refreshed. It is a good alternative to DoEvents (which doesn't exist in B4J and B4i and should be avoided in B4A).

Sub VeryBusySub
   For i = 1 To 10000000
     'do something
     If i Mod 1000 = 0 Then Sleep(0) 'allow the UI to refresh every 1000 iterations.
   Next
   Log("finished!")
End Sub

As demonstrated in the following example, each call to a resumable sub creates a different instance which is not affected by other calls:

Sub btn_Action
   Dim b As Button = Sender
   For i = 10 To 0 Step - 1
     b.Text = i
     Sleep(100)
   Next
   b.Text = "Takeoff!"
End Sub

Wait For

B4X programming language is event driven. Asynchronous tasks run in the background and raise an event when the task completes.
With the new Wait For keyword you can handle the event inside the current sub.

For example, this code will wait for the GoogleMap Ready event:

Sub AppStart (Form1 As Form, Args() As String)
   MainForm = Form1
   MainForm.RootPane.LoadLayout("1") 'Load the layout file.
   gmap.Initialize("gmap")
   Pane1.AddNode(gmap.AsPane, 0, 0, Pane1.Width, Pane1.Height)
   MainForm.Show
   Wait For gmap_Ready '<----------------
   gmap.AddMarker(10, 10, "Marker")
End Sub

A bit more complicated example with FTP:
Listing all files in a remote folder and then downloading all the files:

Sub DownloadFolder (ServerFolder As String)
   FTP.List(ServerFolder)
   Wait For FTP_ListCompleted (ServerPath As String, Success As Boolean, Folders() As FTPEntry, Files() As FTPEntry) '<----
   If Success Then
     For Each f As FTPEntry In Files
         FTP.DownloadFile(ServerPath & f.Name, False, File.DirApp, f.Name)
         Wait For FTP_DownloadCompleted (ServerPath2 As String, Success As Boolean) '<-----
         Log($"File ${ServerPath2} downloaded. Success = ${Success}"$)
     Next
   End If
   Log("Finish")
End Sub

When the Wait For keyword is called, the sub is paused and the internal events dispatcher takes care to resume it when the event is raised. If the event is never raised then the sub will never be resumed. The program will still be completely responsive.
If Wait For is later called with the same event then the new sub instance will replace the previous one.

Lets say that we want to create a sub that downloads an image and sets it to an ImageView:

'Bad example. Don't use.
Sub DownloadImage(Link As String, iv As ImageView)
   Dim job As HttpJob
   job.Initialize("", Me) 'note that the name parameter is no longer needed.
   job.Download(Link)
   Wait For JobDone(job As HttpJob)
   If job.Success Then
     iv.SetImage (job.GetBitmap) 'replace with iv.Bitmap = job.GetBitmap in B4A / B4i
   End If
   job.Release
End Sub

It will work properly if we call it once (more correctly, if we don't call it again before the previous call completes).
If we call it like this:

DownloadImage("https://www.b4x.com/images3/android.png", ImageView1)
DownloadImage("https://www.b4x.com/images3/apple.png", ImageView2)

Then only the second image will show because the second call to Wait For JobDone will overwrite the previous one.
This brings us to the second variant of Wait For.
To solve this issue Wait For can distinguish between events based on the event sender.
This is done with an optional parameter:

Wait For (<sender>) <event signature>

Example:

'Good example. Use.
Sub DownloadImage(Link As String, iv As ImageView)
   Dim job As HttpJob
   job.Initialize("", Me) 'note that the name parameter is no longer needed.
   job.Download(Link)
   Wait For (job) JobDone(job As HttpJob)
   If job.Success Then
     iv.SetImage (job.GetBitmap) 'replace with iv.Bitmap = job.GetBitmap in B4A / B4i
   End If
   job.Release
End Sub

With the above code, each resumable sub instance will wait for a different event and will not be affected by other calls.

Code Flow

Sub S1
Log("S1: A")
S2
Log("S1: B")
End Sub

Sub S2
Log("S2: A")
Sleep(0)
Log("S2: B")
End Sub

The output is:
S1: A
S2: A
S1: B
S2: B

Whenever Sleep or Wait For are called, the current sub is paused. This is equivalent to calling Return.

Wait for a resumable sub to complete and return values from a resumable sub:

https://www.b4x.com/android/forum/threads/b4x-resumable-subs-that-return-values-resumablesub.82670/

Notes & Tips

- Resumable subs cannot return a value.
- The performance overhead of resumable subs in release mode should be insignificant in most cases. The overhead can be larger in debug mode. (If this becomes an issue then take the slow parts of the code and move them to other subs that are called from the resumable sub.)
- Wait For events handlers precede the regular event handlers.
- Resumable subs do not create additional threads. The code is executed by the main thread, or the handler thread in server solutions.

 

[ByteCounter]

How do you deal with resumable subs inability to return values?

I have a sub that benefits from using Sleep() as a timeout delay (while waiting on Astreams NewData event which sets a DataReceived Flag if data was received). The Sleep command pauses the resumable sub, allows other message events to be processed (i.e. NewData) and eventually the Sleep finishes and the resumable sub continues execution after the Sleep() command.
After the Sleep delay I check the DataReceived Flag and I would like to return a boolean true/false flag to the resumable sub caller.

I could use a global flag which is checked after calling the resumable sub but I'm just wondering if there is a better way that I haven't thought of.

Note that I understand why the resumable sub can't return data to the caller ("Whenever Sleep or Wait For are called, the current sub is paused. This is equivalent to Return" and "Calling Sleep or Wait For is equivalent to calling Return from the caller sub perspective."

How to return data to resumable sub caller?

 

[EnriqueGonzalez]

with this you can return a value to the calling sub:

private sub log1 
log2 
wait for log2_completed(r as string)
log(r)
end sub

private sub log2 
dim r as string = "Hello"
sleep(1000)
callsubdelayed2 (me,log2_completed,r)
end sub

 

[Erel]

How do you deal with resumable subs inability to return values?

https://www.b4x.com/android/forum/threads/b4x-resumable-subs-sleep-wait-for.78601/page-2#post-499130

Small typo in Enrique code, it should be:

callsubdelayed2 (me,"log2_completed",r)

 

[LucaMs]

You can call Sleep(0) for the shortest pause. This can be used to allow the UI to be refreshed. It is a good alternative to DoEvents (which doesn't exist in B4J and B4i and should be avoided in B4A).

I fear that you cannot replace DoEvents with Sleep(0) to allow refreshing the GUI because Sleep, even if the time is set to 0, returns control to calling routines.

So, I don't see other good alternative to DoEvents.

 

[Erel]

This is not the correct place to start a discussion. Sleep is a good alternative to DoEvents. You should of course understand how it works. If you want to discuss anything then please start a new thread in the questions forum.

 

[LucaMs]

This is not the correct place to start a discussion

Sorry, you're right.

If you want to discuss anything then please start a new thread in the questions forum.

Done: https://www.b4x.com/android/forum/threads/sleep-0-as-alternative-to-doevents.80127/

 

[devpialkt]

is "wait for" ready for websocket client ?

 

[Erel]

Yes.

 

[devpialkt]

any sample or link code to check is connected, refused, or disconnected with "Resumable Wait For"?

Yes.

 

[Erel]

Please start a new thread in the questions forum.

 

[devpialkt]

here ty

 

[rossati]

Wait for is a good enhancement my be the next step is to return data?

 

[EnriqueGonzalez]

as explained in the post #42,

wait for is completly capable of returning data.

 

[Erel]

Post #42: https://www.b4x.com/android/forum/threads/b4x-resumable-subs-sleep-wait-for.78601/page-3#post-506651

Explanation: https://www.b4x.com/android/forum/threads/b4x-resumable-subs-sleep-wait-for.78601/page-2#post-499130

 

[FabioG]

Hello,

I have a problem

I have this part of code

Sub Start

ProgressDialogShow2("Wait Please",True)

....other code....

Wait(500)

...bla bla bla

End Sub


Sub Wait(MilliSecondi As Int)
   Dim Ti As Long
   Ti = DateTime.Now + (MilliSecondi)
   
   Do While DateTime.Now < Ti
      DoEvents
    Loop
   
End Sub

If I remove DoEvents, ProgressDialog does not appear
I tried to replace DoEvents with Sleep(0) but it does not work



Any tips?

 

[Erel]

You should delete the Wait sub and replace it with Sleep(500).
For further discussion please start a new thread in B4A forum.

 

[FabioG]

Thanks

 

[luciano deri]

I don't think that you are using Wait For correctly. It is not needed in the code you posted.

Example of using Sleep to update the progress bar inside a long loop:

Sub SubThatDoesAVeryLongCalculation
   Dim mx As Long = 100000000
   Dim i As Long
   For i = 1 To mx
     If i Mod 10000 = 0 Then
       ProgressDlg.ProgressUpdate(i * 100 / mx)
       Sleep(0)
     End If
   Next
End Sub

Note that I made a few changes to your project. See the attachment.

Is there something of similar for B4A?

 

[Erel]

Please start a new thread in B4A questions forum.

 

[moore_it]

how i do for kill an resumable sub from UI ?