Ultimate Kotlin-Coroutines Cheat-Sheet

What's This?

• Before Getting Started You Must Know The Difference Between Main Thread And Background Thread:

Main Thread-> Main Thread Is Used To Handle All Those UI Updates In Your Android App. Main Thread Is Also Known As UI Thread As Its Main Work Is To Handle The UI Updates.

Background Thread-> Background Thread(s) Is Used To Handle Long-Running Operations In Your Android App [Eg: Loading Images From Backend, Running Any ML Algorithm, Network Access Etc..].

In Conclusion, You Can Say That

Background Threads Are To Handle Long-running Operations/Tasks While The Main Thread Continues To Handle UI Updates.

But What Is The Purpose Of Coroutines Here😒?

• Well, You Can Handle All Those Background Tasks/Operations With Coroutines In A Better Way.

**Before Going To Further Watch This Clip (From Kotlin Official Site) To Understand How Thread(s) Helps Task(s) To Execute. **

• Coroutines: Coroutines Is A Better Way To Write Asynchronous Code Which Is Perfectly Readable And As Well As Maintainable.

Coroutines can be imagined as lightweight threads, but several important differences make their real-life usage very different from threads.

Let's Test Our First Coroutine:

• Note: You Need To Import import kotlinx.coroutines.* To Get Started With Coroutines.

• Run the Above code to get to your first working coroutine.

Your Output May Look Like This👇🏻

But What Does Our Code Mean🤔?

• launch is a coroutine builder. It launches a new coroutine concurrently with the rest of the code, which continues to work independently. That's why Stay is printed first.

• delay is a special suspending function. It delays the coroutine for a specific time [That Specific Time Should Be Provided In delay's parentheses (delay time in ms)].

• runBlocking is also a coroutine builder that connects the non-coroutine code of a regular fun main() and the code with coroutines inside of runBlocking { ... } curly braces.

• If You Remove or Skip runBlocking in this code, you'll get an error on the launch call, since launch is declared only in the CoroutineScope.

Now, What Is Mean By CoroutineScope?

• The scope simply provides lifecycle methods for coroutines and allows us to manage coroutines to start and stop them.

In Short: scope Provides lifecycle methods for coroutines and allows us to start and stop coroutines.

• Every coroutine builder (like launch, async, etc) is an extension on CoroutineScope and inherits its coroutineContext to, automatically generates all its elements and cancellation.

• We Have coroutineScope { } As Well Beside's launch and runBlocking.

But How Can We Launch **Coroutines In Android**🤔?

• Before Moving To Further Make Sure That You Have Included Coroutines Dependency If It's Not Included:

• We Can Launch A Coroutine By Assigning GlobalScope.launch{ } In Your Main Thread Or Any Other Coroutine:

Note: You Should NOT Use GlobalScope every time.

• Let's Check If Our Coroutine Is Working Or Not By Assigning Log In Our Coroutine:

• Run The Application And Open Logcat To Check The Result:

• And As You Can See That Log Is Executing In Background Thread.

Note: In Your Logcat, Dispatcher Worker's Numerical May Differ[Don't Worry About That].

• You Can Launch Multiple Coroutines From The Declared Coroutine Itself And You Don't Need To Specify Scope every time Inside The Declared Scope:

• Run The Application And Open Logcat To Check The Result:

• And As You Can See That Log Is Executing In Background Thread.

Suspend Functions

Suspend Function Can Execute Long-Running Operations || Tasks And Will Wait For It To Complete Without Blocking The Whole Code.

• Suspend Function Can Be Only Implemented In Another Suspend Function || Coroutine.

• delay() Is Also A Suspend Function,

If You Are Trying To Implement delay() In Your Code, Your IDE May Show This Image In The Numerical Panel Where You Have Implemented A Suspend Function:

This Image Simply Means That You Are Implementing A Suspend Function.

Let's Build A Suspend Function In Android To Deep-dive:

• For Creating A Suspend Function We Need To Mention suspend Before You Create The Function:

• Returning A String Value From The delaying() Function:

• Let's Launch A Coroutine By Assigning GlobalScope.launch{ } In Your Main Thread:

• Now Let's Implement delaying() In Coroutine:

• Let's Assign Log To Check If The delaying() Is Working Or Not:

• Now Run The Application And Open Logcat To Check The Result:

Coroutine Contexts

• Every Coroutine Launches With A Specific Context And This Context Will Describe That In Which A Specific Thread/Coroutine Will Launch In.

• We Have Only Used GlobalScope.launch{ } To Launch A New Coroutine Which Doesn't Give Full Flexibility Which We Want.

• To Overcome That Limitations We Have Something Known As Dispatchers

Now, What Is Mean By Dispatchers🤔?

Dispatchers Determine What thread or threads the corresponding coroutine uses for its execution.

• All Coroutine Builders Like launch and async Accept An Optional CoroutineContext Parameter That Can Be Used To Explicitly Specify The Dispatcher For The New Coroutine.

• We Have 4 Dispatchers Which Are Used For Different Things:

  • Dispatchers.Main

  • Dispatchers.IO

  • Dispatchers.Default

  • Dispatchers.Unconfined

1. Dispatchers.Main : Main Dispatcher Allows Us To Control UI Elements From A Coroutine Which Will Be Executed As The Main Thread From A Coroutine Itself.

• But How Can We Implement Main Dispatcher🤔?

• It's Simple:

• In Android Studio Your Code May Look Like This👇🏼

• You Can Use Log To Check Whether Main Dispatcher Is Running In MainDispatcher Or Not:

• After Successful Launch Of Your Application, Open Logcat To Clarify It.

• As You Can See That It Is Executing In Main Dispatcher As We Declared It As Main Dispatcher.

• But How Can We Control UI After Specifying Main Dispatcher🤔?

• You Can Use Viewbinding, Synthetics, Extensions[Depricated], Or Other Alternatives For Controlling UI From A Coroutine After Specifying Main Dispatcher.

Example:-

• In My .XML File I Have Added A Simple TextView:

• And In The .kt File, I Have Specified A Block Of Code Which Will Change The Text, Inside The Coroutine Including Main **Dispatcher ** So That I Can Work With UI.

• And Launching The Application After Successful Build:

-As You Can See That It Works Like Charm🥳

• But In Case If You Didn't Specify Main Dispatcher If You Want To Control UI Elements From A Coroutine, You'll Get This Beautiful Error In Your Logcat After Launching The Application Which Says:

This Error Occurs If You Didn't Mention It As Main Dispatcher. Because UI Elements Can Be Controlled Only From The Main Thread.

2. Dispatchers.IO : IO Dispatcher Is Used To Control || Execute All Those Data Operations Such As Networking, Writing/Adding Data In Database(s), Reading || Writing The Files.

• But How Can We Implement IO Dispatcher🤔?, It's Simple:

3. Dispatchers.Default : Default Dispatcher Can Be Used To Run Long Operations || Long Tasks Which Will Make Main Thread As A Unresponsiveness. To Avoid Unresponsiveness In Your App, You Can Use Default Dispatcher.

• But How Can We Implement Default Dispatcher🤔?, It's Simple:

4. Dispatchers.Unconfined : Unconfined Dispatcher Is Not Confined To Any Specific Thread. In Other Words, The Unconfined Dispatcher Is Appropriate For coroutines That Neither Consume CPU Time Nor Update Any Shared Data (like UI) Confined To A Specific Thread.

• But How Can We Implement Unconfined Dispatcher🤔?, It's Simple:

• In Case, If You Are Thinking That Is It Possible To Launch Multiple Coroutines From The Same Coroutine Builder Including Dispatchers?

And The Answer Is:

• Yes, It's Possible:

• I Have Assigned Log So That We'll Be Knowing That, AreThese Really Executing In Coroutine Dispatcher's Or Not.

• And As You Can See That Multiple Launches From The Same Coroutine Builder Works Like Charm🥳:

runBlocking()

• You May Know That delay() Is A Suspend Function That delays a coroutine for a specific time. But It Won't Block Whole Thread.

• However, We Have Something Know As runBlocking In Coroutines Which Will Start A New Coroutine When You Assign It, Which Starts In Main Thread By Default.

• Before Going To Further, I Want To Clear That runBlocking Will Block Whole Thread But GlobalScope.launch(...){ } Won't.

Confusing🤔? Not A Problem🙌,

Here Are Two Examples Which May Clear That Confusion:

1. If If Implement delay() In GlobalScope.launch(...){...}, I Can Still Able To Operate UI From My Coroutine Even runBlocking() Is Executed:

• Logcat Info: Launched Activity Info+Activity:
• And As You Can See In Both Logcat And In Mobile, It's Working Like Charm Even runBlocking() Is Executed, It's Because I Haven't Implemented Anything In runBlocking().

2. In This Example I'll Implement delay() In runBlocking(), So That You'll Get An Idea About runBlocking() And What's The Actual Use In Real.

• Logcat Info:

• Launched Activity Info+Activity:

• And As You Can See In Both Logcat And In Mobile, Main Thread Has Been Blocked Including GlobalScope.launch(...){...} (As It's Dealing With Main Thread Too) For A Certain Time And When That Time Has Completed runBlocking() Immediately Releases The Block After It's Execution And Back To Normal State.

I Hope Your Confusing Regarding runBlocking() Has Cleared.

• We'll That's It About runBlocking(), But Why Would Someone Block UI Updates Or Other Stuff In The Application🤔?

• It Can Be Useful If You Don't Necessarily Need Any Particular Coroutine Behaviour But Still Want To Call A Suspend Function In Your Main Thread.

• Another Use Case Scenario Is When You Are Testing With j-unit To Actually Access Suspend Function Within In A Test Function.

• And My Personal Experience With runBlocking() Is That You Can Actually Play Around With Coroutines And runBlocking() To Check What's Actually Going On In Coroutines. In Other Words To Check Behind-The-Scenes Of Coroutines.

• And Yes, The Whole Code In runBlocking() Will Be Synced With Our Normal MainThread Flow.

• As I Mentioned That * runBlocking Will Start A New Coroutine When You Assign It*, That Mean We Can Launch Multiple Coroutines From The runBlocking Too.

-Let's Check That:

• As You Can See That I Have Added The Code In Multiple Launches Which Will Change The logs In runBlocking() Itself And Once runBlocking() Execution Completes It Directly Jumps To Another CodeBlock, In Our Case, It Is GlobalScope.launch(...){...} And App Will Notify Those Changes In Both Logcat And In Application:

• And When You Are Trying To Implement Multiple Coroutine Launches From runBlocking(), It Will Execute All Those Launches Simultaneously At The Same Time As You Can See Timing In Logcat Too When Both Of The Logs From Two Launches Executed From runBlocking():

Coroutine Jobs

• Whenever We Launch A Coroutine It Returns A Job. In Other Words, It Returns The Work Which We Have Assigned . Ex:- Loading Data, Network Operations, Working With UI, Some Background Stuff Etc.,

• These Job(s) || Work Which You Have Assigned In Coroutines Can be Saved In A Variable Too:

• Which May Look Like This In Your Android Studio || Other IDE Which You Use:

Jobs:

-> Now In Case If You Want To Finish This Particular Variable's Task Primarily Rather Than Other Task(s) Then Jobs May Help You.

• Before Getting Started I Want To Clear You That Jobs Is Not A Function. We Have Multiple Suspend Functions And Other CodeBlocks Which Can Make Our Job Easy😉:

• .join()

• .cancel()

• Now, These Suspend Functions And Other CodeBlocks Can Be Defined As Jobs Through Coroutine Builders.

• Let's Go In-Deep To Check What Actually These Functions Do And How Can Be Used And When These Can Be Used.

• I'm Going To Use runBlocking(), So That We'll Get An Idea How & When These Functions Can Be Used.

• runBlocking() Blocks Whole Thread Until The Execution Of runBlocking() Completes.

-> If You Don't Want To Execute That Variable Primarily Or Don't Want To Execute In runBlocking(), You Can Execute That Variable In A Coroutine As Well:

.join():

As Name Suggests, Our Job||Work Can Join Some other Suspend Function Or Coroutine.

• Whenever We Have Assign .join() Or Other Jobs In runBlocking() The Execution Of Variable Completes First And Then Back To The Normal State Of Our Code.

• That Mean When Ever We Have Assigned .join() Or Other Jobs To A Variable Where We have Stored Our Coroutine Execution Will Primarily Completes First And Then Remaining Execution Of Other Code Block Will Be Continued. [If You Are Working With runBlocking()]

• As You Can See That I Have Added Multiple Coroutines With Individual Coroutine Builders Where I Have Assigned One Of The Coroutines In A Variable Named work To Demonstrate:

Case1:

• If .join() Is Executed In runBlocking():

• And Make Sure That You Have Implemented work.join() In runBlocking() As .join() Is A Suspend Function.

• As You Can See In Both Logcat+Mobile Activity Our Variable Is Executed First And Then Other Coroutine Started Their Respected Work/Job Where Variable Is Included In runBlocking():

Case2:

• If .join() Is Executed In Coroutine:

• And Make Sure That You Have Implemented work.join() In Coroutine As .join() Is A Suspend Function.

• As You Can See In Both Logcat+Mobile Activity Our Variable Is Executed Simultaneously With That Particular Coroutine In Which I Have Implemented work Variable And Then Other Coroutine Started Their Respected Work/Job As Well:

• And You Can Notice In Both The Cases That .join() Function Is Executed First.

• That's All About .join() Which Can Be Joined In Other Coroutine To Work Simultaneously With That Coroutine || In runBlocking() To Execute That Variable Primarily.

.cancel():

As Name Suggests, Our Job||Work Can Be Cancelled.

• But Why Would Someone Cancel The Work🤔?

• Let's See Those Cases:

• As You Can See That I Have Added A repeat(...){...} Block Where I Have Added Log Statements By 1 Second Delay Interval, By 5 Times.

• That Means Execution Will Be Completed In 5 Seconds.

Case1:

• If .cancel() Is Executed In runBlocking():

• As I Already Mentioned .cancel() Will Cancel Our Work Immediately, So I am Delaying For 2 Seconds After That Our Work || Job Will Be Cancelled.

That Mean repeat's Block Code Will Be Executed 2 Times And Then The Whole Work Will Be Cancelled.

• And Make Sure That You Have Implemented work.cancel() In runBlocking() As .cancel() Is A Suspend Function.

• As You Can See In Logcat That Our Variable Is Executed 2 Times And Then It Got Canceled Immediately:

Case2:

• If .cancel() Is Executed In Coroutine:

• As I Already Mentioned .cancel() Will Cancel Our Work Immediately, So I am Delaying For 2 Seconds After That Our Work || Job Will Be Cancelled.

That Mean repeat's Block Code Will Be Executed 2 Times And Then The Whole Work Will Be Cancelled.

• And Make Sure That You Have Implemented work.cancel() In Coroutine As .cancel() Is A Suspend Function.

• As You Can See In Logcat That Our Variable Is Executed 2 Times And Then It Got Canceled Immediately:

However Cancelling A Coroutine Is Not Easy Always As I have Demonstrated And Cancelled Above, In Few Cases It May Just Crash The Whole Code As Well If You Didn't Properly Handle It. By The Way Most Of The Time, You May Execute withTimeOut(...){...} Rather Than Cancelling The Coroutine Which Makes Things More Simple Though.

• That's All About .cancel() Which Can Cancel The Execution (If You Want).

isActive:

• With .cancel() We Can Cancel The Execution But The Job || Work Which We Have Executed To A Variable Won't Know That Job || Work Has Cancelled, To Over Come That isActive() Can Be Used With if Statement As I Have Demonstrated Below:

• In Other Words, You Can Manually Check That Is Our Coroutine Active Or Not:

• As You Can See That Once Coroutine Knows That Job Is Canceled It Will Leave The Execution.

• And If You Actually Notice The Code You'll Notice That If Haven't Added work.join But The Code Is Executing As I Have Added It, How's That Possible🤔?

• It's Because As I Have Added isActive In The Code, The Variable Continues To Work Until That Particular Variable Is Cancelled; As It Didn't Get Cancelled That Mean It's Still Active To Execute. That's The Reason Even Though I Didn't Mention work.join, Coroutine Will Work Like Charm ⚡. But Once That Variable Gets Cancelled The Variable Will No Longer Be Active.

withTimeOut(...){...}:

• If You Are Thinking That "Is It Possible To Set A Particular Time And If That Work || Job Didn't Get Completed In That Particular Time It Should Be Cancelled Automatically" Without runBlocking().

• And The Answer Is:

• Yes It's Possible With withTimeOut(...){...} In Which You'll Give A Specific Time If That Job || Work Didn't Get Completed Within That Particular Time It Will Be Cancelled Automatically Without Any runBlocking() And Other Stuff:

• As You Can See That Once The Given Time Completes Coroutine Is Cancelled Automatically:

async && await

Case Scenario

• You May Already Know That When You Have Implemented Respective Codeblock In Your Code It Will Execute Sequentially.

• In Other Words, They'll Be Executed One-By-One By Default.

• But In Few Cases, You May Need To Start The Execution Of Multiple Codeblocks At A Time Where Output || Result Timing May Vary.

• In Those Case Scenario's You Need To Work Asynchronously With Your Respective Codeblock Which Means You Need To Start Those Codeblock's Execution At A Time.

Asynchronous = Running Multiple Codeblocks At A Time Where Result || Output Will Be Returned || Executed Later On.

Introduction To async

• Now, As I Mentioned Earlier That If You Want To Start Executing At A Time Then You Should Work Asynchronously.

• In Kotlin, We Have Something Known As async Which Is Of Type Deferred From Which We Can Build Our Respective Codeblock Asynchronously.

• async Doesn't Return A Job Which Is Also A Coroutine Builder.

• As You Can See Below That async Is Of Type Deferred:

Introduction To await

• As I Mentioned Above That async Will Help You To Work Asynchronously But It May Stop Other Execution Too🤷🏼‍♂️.

• To Avoid That And We'll Be Using await Method With async So That Remaining Codeblock Execution Will Be Normal.

In Other Words, await Ensures That The Execution Will Go Further Until The Function Is Executed Completely.

Use Case Scenario's

• As You Can See That I Have Created 2 Suspend Functions:

• And I'll Be Delaying For 2 Seconds And Returning A String In Both Functions Respectively:

Case 1

Code Without Asynchronous

• I'll Implement Those Suspend Functions In A Coroutine With GlobalScope And With launch Coroutine Builder Through IO Dispatcher:

• Now If You'll Launch The Application After Successful Build You'll Notice That It Takes 4 Seconds To Log Those Messages Which I Have Given.

• It's Because apiCall1() And apiCall2() Suspend Functions Delays 2 Seconds Respectively Before Returning Those Values.

• If You Want To Measure The Time Taken To Complete Those Executions We Have Few Classes || Methods. In My Case,

• I'll Be Using measureTimeMillis{...} Which Returns Us The Time Taken To Complete The Execution Which We Have Implemented In That Particular Method || Class In Milliseconds Format.

• You Can Use measureTimeMillis{...} In A Variable So That You Can Get The Duration Of That Execution:

• Now Let's Add Those Suspend Functions In time Variable In Order To Get The Time Taken To Complete The Execution.

• And As You Can See That It Took 4 Seconds To Complete:

• It's Because We Are Not Executing Our Code Asynchronously, So It Executes Sequentially By Default.

Case 2

Coding Asynchronously

• Make Sure That You Have Added async{...} To Work Asynchronously.

• Coding Asynchronously Doesn't Make Your Codeblock To Cook The Result Primarily, It Makes Sure That Your Particular Codeblock Will Be Executed Primarily Rather Than The Result || Output.

• I'll Be Implementing Both Of The Suspend Functions In Two Different Variables With async In A Coroutine For Demonstration:

Now, It's The Moment Of Truth🔥.

• Let's Implement Our Above Code BLock Where We Are Working Asynchronously In measureTimeMillis{...} So That We Can Get The Duration Of The Execution.

• And Make Sure That You Have Implemented await() Method With our Variables So That Remaining Codeblock [If Any] Execution Will Be Normal Without Any Problem(s):

• And As You Can See That Both Of The Suspend Functions Are Executed Simultaneously, Which Means Execution Is Now Completed In 2 Seconds Itself:

• Well, As You Can See That It Worked Asynchronously🤙🏼.

Why Using GlobalScope Is Discouraged

• When We Use GlobalScope To Launch A Coroutine It Will be Launched In Top-Level Coroutine As It's Global And It Will Be Remained Until Your Application Is Dead.

In Other Words:

• If You Are Using GlobalScope To Launch A Coroutine It Will Be Alive Until Your Application Is Dead Even You Have Skipped The Particular Activity || Fragment Where That Particular Corotuine Has Been Launched.

• As You Already Know That Coroutines Are Light-Weight But Still It Will Consume Some Memory Resources While It's Running For Sure, Which May Cause Memory Leaks In Your Application.

Solution

• You Can Use Pre-Defined Scopes Such As lifecycleScope{...} And If You Are Working With ViewModel(s) You Can Use viewModelScope{...} To Launch A Coroutine And Get Started.

Practical Difference

Let's Test With Both GlobalScope{...} And lifecycleScope{...} For Better Understanding

• I Have Created Two Fragments And Added Navigation Between Both Fragments Through Navigation Component.

First Fragment's XML:

Second Fragment's XML:

Time For The Truth🔥

Before Moving To Further Make Sure That You Have Included Coroutines Dependency If It's Not Included:

In First Fragment's Kotlin File:

With GlobalScope{...}

• Primarily Coroutine Will Be Launched Asusal With GlobalScope{...} When Button Is Pressed.

• When Button Will Be Pressed An Infinite Loop Will Run With A Second Delay every time.

• After 5 Seconds Delay, Second Fragment Will Be Launched As You Can See Below In The Code:

• Now Launch The Application After A Successful Build:

• As You Can See That Even Though First Fragment Has Dead Our Loop Still Continues As We Declared Our Scope As GlobalScope{...} Which Will Continues To Run Until Our Application Is Dead.

• This Is The Main Reason Why Using GlobalScope Is Discouraged In Kotlin-Coroutines.

With lifecycleScope{...}

• Primarily Coroutine Will Be Launched Asusal With lifecycleScope{...} When Button Is Pressed.

• When Button Will Be Pressed An Infinite Loop Will Run With A Second Delay every time.

• After 5 Seconds Delay, Second Fragment Will Be Launched.

As You Can See In The Code That I Have Mentioned viewLifecycleOwner Before Launching The Coroutine With lifecycleScope{...}

• It's Because I am Working With Fragments. viewLifecycleOwner Is Added When The Fragment Has Its UI ( onCreateView() , onDestroyView() ) This Is Added To The Fragment's Overall Lifecycle ( onCreate() , onDestroy() ).

• In case, If You Are Working With Activities You Don't Need To Mention viewLifecycleOwner.

• Now Launch The Application After A Successful Build:

• As You Can See That Once The Fragment Has Dead Coroutine Execution Has Stopped.

Same Implies To viewModelScope{...} As Well, It Will Also Perform Same As lifecycleScope{...}. But You'll Be Using viewModelScope{...} When you Are Working With ViewModel(s).

Conclusion

• Use GlobalScope{...} When You Want An Operation To Run Until The Application Is Dead If Not You Should Definitely Use lifecycleScope{...}.

• If You Are Working With ViewModel(s) You Can Use viewModelScope{...}.

Well, That's All For Now🙌

Bye🤗