Rename Task.blocking to Task.callableInExecutor

[junchuanwang]

ParSeq beginner users are often confused about the name of "Task.blocking". It is even more confusing if comparing with other task creating apis: Task.callable, Task.async, Task.action, Task.value.
(I personally think Task.async confusing as well..)

By analogy, Task.callable means to create a task with a callable. Task.value means to create a task with a value. I think Task.callableInExecutor is a better user-facing name. It means to create a task that would create "a callable that run in executor".

[aman1309]

can you add java doc to redirect to new method

[aman1309]

update blocking to runInExecutor. same for other places

[junchuanwang]

I think here the word blocking does not need to be replaced.

[aman1309]

text will point to #blocking method but link for new method in parsed doc. It will be confusing since we can't remove blocking method

[aman1309]

update test name

[karthikbalasub]

Though the naming was bad before, the need to pass executor as an argument would've given enough hint to the user about the behavior. Also, most of the existing users would now be familiar with Task::blocking behavior. So deprecating it might cause push back from such users.
What I'm trying to say is, this is one of those cases where you cannot satisfy every user. It comes down to personal preferences..

Another ambiguity is that "run" might imply the returned task is running already. However, the task still needs to be run by calling Engine::run. Maybe use "runCallableInExecutor" ?

[karthikbalasub]

Comment on the replacement to use.

[junchuanwang]

udpated

[karthikbalasub]

Comment on the replacement to use.

[junchuanwang]

udpated

[junchuanwang]

Though the naming was bad before, the need to pass executor as an argument would've given enough hint to the user about the behavior. Also, most of the existing users would now be familiar with Task::blocking behavior. So deprecating it might cause push back from such users.
What I'm trying to say is, this is one of those cases where you cannot satisfy every user. It comes down to personal preferences..

Another ambiguity is that "run" might imply the returned task is running already. However, the task still needs to be run by calling Engine::run. Maybe use "runCallableInExecutor" ?

@karthikbalasub I am not worried about existing user familiar with Task::blocking thing, becuase I don't believe there will be anyone who would not understand what happened after seen the java doc. Push back? maybe, but I think the team has the final say and that's why I am checking if the team would agree with me.

For the naming, maybe just "calalbleInExecutor"?

[evanw555]

1. In the method body of the new method, I still see a blockingTask.getShallowTraceBuilder().setTaskType(TaskType.BLOCKING.getName());, is this something that may cause confusion or inconsistency, since it's no longer Task.blocking yet it uses TaskType.BLOCKING?
2. On Karthik's point, the fact that there's an executor argument may be enough of a hint. If we're saying it's just the same as callable but with an executor, can we not just overload Task.callable? Task.callable(name, callable, executor)? May not make sense to pack redundant info into the method name. This would arguably be cleaner.

[junchuanwang]

@karthikbalasub @evanw555 I do see benfit of using Task.callable(name, callable, executor) (it is cleaner).

But the problem is it seems that in ParSeq history, callable and callableInExecutor (or blocking, as its previous name) were made distinct.

The fact is in history, there was asyncCallableTask, than the Task.blocking. So we are kind of reverting things back

[junchuanwang]

Link to #289