Command in Tcl 8.6:
    :   '''yieldto''' ''command'' ?''arg …''?
Suspends the current [coroutine] and makes the current coroutine's caller invoke ''command'' (with the optional ''arg''s). ''Command'' is resolved prior the suspension in the context of the current coroutine, and can refer to another coroutine (though this is not required). May only be called from within a [coroutine]; it is an error to call it from elsewhere.

Exceptions:
    :   '''TCL COROUTINE ILLEGAL_YIELD''' — if called from an illegal context (i.e., not in a coroutine).
    :   '''TCL COROUTINE CANT_YIELD''' — there is a coroutine context, but a non-NRE-aware C command is gumming up the works.

When resumed, returns the ''list'' of arguments passed to the coroutine's resumption command. (This is different to [yield], which makes the resumption command take a single optional argument that defaults to the empty string.)

[[This wiki page has a capital letter in its name for historical reasons.]]

----
<<discussion>> Prehistory
New experimental command added in ::[tcl::unsupported] on 2009-12-07.

    :   '''[tcl::unsupported]::yieldTo''' ''command'' ?''arg ...''?

Suspends the current [coroutine] and makes the current coroutine's caller invoke ''command'' (with the optional ''arg''s). ''Command'' is resolved prior the suspension in the context of the current coroutine, and can refer to another coroutine (though this is not required). May only be called from within a [coroutine]; it is an error to call it from elsewhere.

Exceptions:
    :   '''TCL COROUTINE ILLEGAL_YIELD''' — if called from an illegal context (i.e., not in a coroutine).

Docs forthcoming, for now just the tclcore thread at [http://aspn.activestate.com/ASPN/Mail/Message/tcl-core/3789015]

----
[AMG]: Why is this command named with an internal capital letter?  All other built-in Tcl commands (as opposed to utility procs) are named with multiple words (or abbreviations thereof) jammed together with no capitals or underscores.  Examples abound: [[[bgerror]]], [[[fblocked]]], [[[foreach]]], [[[gets]]], [[[lappend]]], [[[regexp]]], [[[uplevel]]], and [[[vwait]]].

[MS] no special reason

[CRC] From the thread, it appears that the author of this code just likes, or is used to, camel case.  In the ensuing discussion it was referred to as "yieldto".  Not being a fan of camel case myself, I hope that if it gets incorporated, it is "yieldto", or "yield -target" as [DKF] suggests.

'''[DGP]''' FWIW, there are precedents in the other direction as well:  [pkg_mkIndex], [tcl_findLibrary], [tcl_endOfWord], etc.

[AMG]: Those are the utility procs I was referring to.

-----
[jbr] - I'm wondering why we are polluting the global namespace with yield variants.  Don't people already have complaints about the many list commands and the file io commands not being grouped together?

[AMG]: Same question.  Some time ago there was a discussion on tcl-core regarding [[[yield]]], [[yieldTo]], and [[[yieldm]]].  I don't recall how it was resolved, or even if it was resolved at all.  I advocated unifying these three commands into a single [[yield]] command that takes options.  In addition to cleaning up the global namespace, this would close the gap between [[yieldTo]] and [[yieldm]]: how do you instruct the current coroutine's caller to invoke a command, while making the current coroutine's resume command accept any number of arguments?

<<categories>> Command