improve BlockingTrioPortal documentation

[belm0]

• improve BlockingTrioPortal.run() exception message
• clarify the meaning of "Trio thread"
• clarify that the BlockingTrioPortal.run() thread check applies to any Trio thread

[belm0]

context: https://gitter.im/python-trio/general?at=5d1800979cbde24b2f42b90b

[belm0]

I'll reword the message now that I understand meaning of "trio thread" better, and perhaps expand this PR to define that better in the docs.

[codecov[bot]]

Codecov Report

Merging #1130 into master will not change coverage. The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1130   +/-   ##
=======================================
  Coverage   99.51%   99.51%           
=======================================
  Files         104      104           
  Lines       12631    12631           
  Branches      968      968           
=======================================
  Hits        12570    12570           
  Misses         40       40           
  Partials       21       21

Impacted Files	Coverage Δ
trio/_threads.py	100% <ø> (ø)	:arrow_up:

[codecov[bot]]

Codecov Report

Merging #1130 into master will not change coverage. The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1130   +/-   ##
=======================================
  Coverage   99.51%   99.51%           
=======================================
  Files         104      104           
  Lines       12631    12631           
  Branches      968      968           
=======================================
  Hits        12570    12570           
  Misses         40       40           
  Partials       21       21

Impacted Files	Coverage Δ
trio/_threads.py	100% <ø> (ø)	:arrow_up:

[codecov[bot]]

Codecov Report

Merging #1130 (09c42dd) into master (8b15548) will decrease coverage by 0.06%. The diff coverage is 28.57%.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1130      +/-   ##
==========================================
- Coverage   99.16%   99.11%   -0.06%     
==========================================
  Files         115      115              
  Lines       17514    17528      +14     
  Branches     3125     3125              
==========================================
+ Hits        17368    17372       +4     
- Misses        101      111      +10     
  Partials       45       45              

Files	Coverage Δ
trio/_threads.py	95.34% <28.57%> (-4.66%)	:arrow_down:

[belm0]

so it turns out BlockingTrioPortal docs are not clear that the check applies to any Trio thread, so I clarified that as well

to consider: if the rule is merely about preventing deadlock, perhaps the check could be loosened to only the Trio thread associated with the portal

[njsmith]

What do folks think about using phrasing like "inside trio.run" instead of "inside a/the Trio thread"?

[smurfix]

Well, questions along the lines of "I've started that other thread from inside trio.run so why isn't this working" come to mind.

[njsmith]

I'm afraid I've lost track of the status of this, and in the mean time BlockingTrioPortal has turned into trio.from_thread – though most of the docs were moved over verbatim. @belm0 is this still something you're interested in working on, and if so do you know what the status is?

[njsmith]

@belm0 ping

[Fuyukai]

BlockingTrioPortal got removed four years ago. Closing as this is no longer relevant.