Repository: Kotlin/kotlinx.coroutines
File: kotlinx-coroutines-core/common/src/JobSupport.kt (Kotlin)

Code before:
                            nodeAdded!!.invoke((state as? CompletedExceptionally)?.cause)
                        } else {
                            handler.invokeIt((state as? CompletedExceptionally)?.cause)
                        }
                    }
                    return NonDisposableHandle
                }
            }
        }
    }

    private fun makeNode(handler: CompletionHandler, onCancelling: Boolean): JobNode<*> {
        return if (onCancelling)
            (handler as? JobCancellingNode<*>)?.also { assert { it.job === this } }
                ?: InvokeOnCancelling(this, handler)
        else
            (handler as? JobNode<*>)?.also { assert { it.job === this && it !is JobCancellingNode } }
                ?: InvokeOnCompletion(this, handler)
    }

    private fun addLast(expectedState: Any, list: NodeList, node: JobNode<*>): Boolean {
        list.addLast(node)
        if (this.state === expectedState) return true
        if (node is ChildCompletion && !node.markInvoked()) return true
        node.dispose()
        return false
    }

    private fun promoteEmptyToNodeList(state: Empty) {
        // try to promote it to LIST state with the corresponding state
        val list = NodeList()
        val update = if (state.isActive) list else InactiveNodeList(list)
        _state.compareAndSet(state, update)
    }

    private fun promoteSingleToNodeList(state: JobNode<*>) {
        // try to promote it to list (SINGLE+ state)
        state.addOneIfEmpty(NodeList())
        // it must be in SINGLE+ state or state has changed (node could have need removed from state)
        val list = state.nextNode // either our NodeList or somebody else won the race, updated state
        // just attempt converting it to list if state is still the same, then we'll continue lock-free loop
        _state.compareAndSet(state, list)
    }

    public final override suspend fun join() {
        if (!joinInternal()) { // fast-path no wait
            coroutineContext.checkCompletion()
            return // do not suspend
        }
        return joinSuspend() // slow-path wait
    }

Review comment (suggestion):
This method not only adds to the tail, but does something else, please properly documented it and describe why this machinery is required. Especially `ChildCompletion`

Code after:
                        if (invokeImmediately) {
                            node.invoke(rootCause)
                        }
                        return handle
                    } else {
                        if (!isNodeAdded) list.addLast(node)
                        if (this.state !== state) {
                            // Here again, we try to prevent concurrent finalization of the parent,
                            // if the parent fails to add ChildCompletion because the child changed it's state to Completed.
                            if (node is ChildCompletion && !node.markInvoked()) return node
                            // If the state has changed to Complete, the node can stay in the list, just retry.
                            if (this.state !is Incomplete) return@loopOnState
                            // If the state is Incomplete, set the flag that the node is already added to the list instead of removing it.
                            isNodeAdded = true
                        } else {
                            return node
                        }
                    }
                }
                else -> { // is complete
                    if (invokeImmediately) {
                        node.invoke((state as? CompletedExceptionally)?.cause)
                    }
                    return NonDisposableHandle
                }
            }
        }
    }

    private fun makeNode(handler: CompletionHandler, onCancelling: Boolean): JobNode {
        val node = if (onCancelling) {
            (handler as? JobCancellingNode)
                ?: InvokeOnCancelling(handler)
        } else {
            (handler as? JobNode)
                ?.also { assert { it !is JobCancellingNode } }
                ?: InvokeOnCompletion(handler)
        }
        node.job = this
        return node
    }

    private fun promoteEmptyToNodeList(state: Empty) {
        // try to promote it to LIST state with the corresponding state
        val list = NodeList()
        val update = if (state.isActive) list else InactiveNodeList(list)
        _state.compareAndSet(state, update)
    }

    private fun promoteSingleToNodeList(state: JobNode) {
        // try to promote it to list (SINGLE+ state)