Bug 540685

Summary:	Document which Job#create method to prefer - ICoreRunnable or IJobFunction
Product:	[Eclipse Project] Platform	Reporter:	Lars Vogel <Lars.Vogel>
Component:	Runtime	Assignee:	Lars Vogel <Lars.Vogel>
Status:	RESOLVED FIXED	QA Contact:
Severity:	enhancement
Priority:	P3	CC:	daniel_megert, Lars.Vogel, mikael.barbero, mistria
Version:	4.10	Keywords:	api, Documentation
Target Milestone:	4.18 M1
Hardware:	All
OS:	All
See Also:	https://git.eclipse.org/r/c/platform/eclipse.platform.runtime/+/169012 https://git.eclipse.org/r/c/platform/eclipse.platform.runtime/+/169013 https://git.eclipse.org/c/platform/eclipse.platform.runtime.git/commit/?id=040e6b4019a8253cf167127520b27616d92f6f05 https://git.eclipse.org/c/platform/eclipse.platform.runtime.git/commit/?id=cdb9e278c698dbd7db2fa6608ae54b146e753448
Whiteboard:

Description Lars Vogel

2018-11-01 06:00:21 EDT

Looking at the Jobs#create Javadoc it is unclear which method should be used:

public static Job create(String name, final IJobFunction function) 
public static Job create(String name, final ICoreRunnable runnable)

I suggest we add some Javadoc which method to use them.

Comment 1 Lars Vogel

2018-11-01 06:03:49 EDT

Mikael, could you help here with a Gerrit for the Javadoc? 

I forgot which method we prefer. ;-)

Comment 2 Lars Vogel

2018-11-01 06:30:38 EDT

Looking at the ICoreRunnable Javadoc I think create(String name, final ICoreRunnable runnable) is the "better" API, as I do not have to call done on the ProgressMonitor and it accepts null as ProgressMonitor.

@Mikael, do you agree? In this case I can add, "Prefer using create(String name, final ICoreRunnable runnable)" to the Javadoc of create(String name, final IJobFunction function)

Comment 3 Lars Vogel

2019-02-19 03:32:11 EST

Mass change, please reset target if you still planning to fix this for 4.11.

Comment 4 Mikaël Barbero

2019-06-07 09:53:51 EDT

(In reply to Lars Vogel from comment #2)
> Looking at the ICoreRunnable Javadoc I think create(String name, final
> ICoreRunnable runnable) is the "better" API, as I do not have to call done
> on the ProgressMonitor and it accepts null as ProgressMonitor.
> 
> @Mikael, do you agree? In this case I can add, "Prefer using create(String
> name, final ICoreRunnable runnable)" to the Javadoc of create(String name,
> final IJobFunction function)

+1. It also have the advantage of relying on Exceptions (OperationCanceledException in this case, as reported by SubMonitor.split()) which is much easier than if (pm.isCanceled) { return Status.CANCELED_STATUS; }

Feel free to add me as reviewer of a patch.

Comment 5 Eclipse Genie

2020-09-08 10:20:58 EDT

New Gerrit change created: https://git.eclipse.org/r/c/platform/eclipse.platform.runtime/+/169012

Comment 6 Eclipse Genie

2020-09-08 10:21:00 EDT

New Gerrit change created: https://git.eclipse.org/r/c/platform/eclipse.platform.runtime/+/169013

Comment 7 Eclipse Genie

2020-09-08 11:03:30 EDT

Gerrit change https://git.eclipse.org/r/c/platform/eclipse.platform.runtime/+/169012 was merged to [master].
Commit: http://git.eclipse.org/c/platform/eclipse.platform.runtime.git/commit/?id=040e6b4019a8253cf167127520b27616d92f6f05

Comment 8 Eclipse Genie

2020-09-09 03:11:17 EDT

Gerrit change https://git.eclipse.org/r/c/platform/eclipse.platform.runtime/+/169013 was merged to [master].
Commit: http://git.eclipse.org/c/platform/eclipse.platform.runtime.git/commit/?id=cdb9e278c698dbd7db2fa6608ae54b146e753448