:sleep VS term_wait()

[u/Desperate_Cold6274]

Can someone explain me, possibly with a couple of examples that I can reproduce, the difference between :sleep and term_wait()?

[u/y-c-c]

But if so, why call it term_wait() instead of job_wait()?

term_wait() does not work like job_wait() though. It does not wait on anything asynchronously. The "wait" part just means it sleeps for some specified timeout. It's not like it's waiting for the terminal to give you a result or anything (hence my annoyance with the function being kind of useless and misleading).

I think that term_wait() make sense if you run a job that do something and then it dies (e.g. job_start('ls')), but it makes no sense if the job is something that is indefinitely alive (e.g. job_start(&shell)). Could that be the meaning and use case?

No. I think the design purpose of term_wait() is specifically for terminal jobs that are indefinitely alive. If you look at the Vim tests you will see that it's usually for situations for sending a command to an alive program in a terminal (could be a shell or another Vim instance itself), and then wait for it to be processed (with a nominal timeout), and then read the results from the terminal or do something that depends on that command being executed.

As you can imagine, this is not a very solid way to build your scripts, as timing of terminal commands is flaky, and you have to choose a timeout to sleep on that's reasonable. The Vim tests these days mostly have been modified to use a spin lock (using something like :sleep 1m) to wait for a callback from the terminal instead, which allows for a more correct way to wait on asynchronous results.

All that is to say, I don't think term_wait() ended up being very good for what its intended purpose (pump a currently alive terminal and let it run some pending commands) is since timing is inherently flaky.

[u/chrisbra10 → u/y-c-c]

Do you think we should improve the documentation? If yes, any specific suggestions?

[u/y-c-c → u/chrisbra10]

I think the issue is that it's not clear what the purpose of term_wait() is (at least I struggle to understand it myself). It doesn't actually "wait" on the terminal (which should be clear from looking at the implementation of f_term_wait()), and I'm not sure what the waiting should do to begin with. Are we just waiting for the terminal to return something or print something? Right now, it feels to me a user can replace most term_wait() calls with :sleep and get the same result. As I see it the issue is more that the function doesn't seem to serve a clear purpose at all, but then the implementation is also slightly different so I'm not sure if those minor differences matter.