tillrohrmann commented on a change in pull request #11963:
URL: https://github.com/apache/flink/pull/11963#discussion_r420216851
##########
File path:
flink-runtime/src/main/java/org/apache/flink/runtime/execution/librarycache/LibraryCacheManager.java
##########
@@ -20,91 +20,79 @@
import org.apache.flink.api.common.JobID;
import org.apache.flink.runtime.blob.PermanentBlobKey;
-import org.apache.flink.runtime.executiongraph.ExecutionAttemptID;
-
-import javax.annotation.Nonnull;
import java.io.IOException;
import java.net.URL;
import java.util.Collection;
+/**
+ * The LibraryCacheManager is responsible for creating and managing the user
code
+ * class loaders.
+ *
+ * <p>In order to obtain a user code class loader, one first needs to obtain a
+ * {@link ClassLoaderLease} for a given {@link JobID}. At first, the {@link
ClassLoaderLease}
+ * is unresolved. In order to obtain the user class loader one needs to
resolve it
+ * by specifying the required jar files and class paths. The user code class
loader
+ * for a job is valid as long as there exists a valid {@link
ClassLoaderLease}. A
+ * {@link ClassLoaderLease} becomes invalid once it gets closed.
+ */
public interface LibraryCacheManager {
/**
- * Returns the user code class loader associated with id.
+ * Registers a new class loader lease for the given jobId. The user
+ * code class loader for this job will be valid as long as there
+ * exists a valid lease for this job.
*
- * @param id identifying the job
- * @return ClassLoader which can load the user code
+ * @param jobId jobId for which to register a new class loader lease
+ * @return a new class loader lease for the given job
*/
- ClassLoader getClassLoader(JobID id);
+ ClassLoaderLease registerClassLoaderLease(JobID jobId);
/**
- * Registers a job with its required jar files and classpaths. The jar
files are identified by
- * their blob keys and downloaded for use by a {@link ClassLoader}.
- *
- * @param id job ID
- * @param requiredJarFiles collection of blob keys identifying the
required jar files
- * @param requiredClasspaths collection of classpaths that are added to
the user code class loader
- *
- * @throws IOException if any error occurs when retrieving the required
jar files
- *
- * @see #unregisterJob(JobID) counterpart of this method
+ * Shuts the library cache manager down. Thereby it will close all open
+ * {@link ClassLoaderLease} and release all registered user code class
+ * loaders.
*/
- void registerJob(JobID id, Collection<PermanentBlobKey>
requiredJarFiles, Collection<URL> requiredClasspaths)
- throws IOException;
+ void shutdown();
/**
- * Registers a job task execution with its required jar files and
classpaths. The jar files are
- * identified by their blob keys and downloaded for use by a {@link
ClassLoader}.
- *
- * @param id job ID
- * @param requiredJarFiles collection of blob keys identifying the
required jar files
- * @param requiredClasspaths collection of classpaths that are added to
the user code class loader
- *
- * @throws IOException if any error occurs when retrieving the required
jar files
- *
- * @see #unregisterTask(JobID, ExecutionAttemptID) counterpart of this
method
+ * Handle to retrieve a user code class loader for the associated job.
*/
- void registerTask(JobID id, ExecutionAttemptID execution,
Collection<PermanentBlobKey> requiredJarFiles,
- Collection<URL> requiredClasspaths) throws IOException;
+ interface ClassLoaderHandle {
- /**
- * Unregisters a job task execution from the library cache manager.
- *
- * <p><strong>Note:</strong> this is the counterpart of {@link
#registerTask(JobID,
- * ExecutionAttemptID, Collection, Collection)} and it will not remove
any job added via
- * {@link #registerJob(JobID, Collection, Collection)}!
- *
- * @param id job ID
- *
- * @see #registerTask(JobID, ExecutionAttemptID, Collection,
Collection) counterpart of this method
- */
- void unregisterTask(JobID id, ExecutionAttemptID execution);
-
- /**
- * Unregisters a job from the library cache manager.
- *
- * <p><strong>Note:</strong> this is the counterpart of {@link
#registerJob(JobID, Collection,
- * Collection)} and it will not remove any job task execution added via
{@link
- * #registerTask(JobID, ExecutionAttemptID, Collection, Collection)}!
- *
- * @param id job ID
- *
- * @see #registerJob(JobID, Collection, Collection) counterpart of this
method
- */
- void unregisterJob(JobID id);
+ /**
+ * Gets or resolves the user code class loader for the
associated job.
+ *
+ * <p>In order to retrieve the user code class loader the caller
+ * has to specify the required jars and class paths. Upon
calling this
+ * method first for a job, it will make sure that the required
jars are
+ * present and potentially cache the created user code class
loader.
+ * Every subsequent call to this method, will ensure that
created
+ * user code class loader can fulfill the required jar files and
+ * class paths.
+ *
+ * @param requiredJarFiles requiredJarFiles the user code class
loader needs to load
+ * @param requiredClasspaths requiredClasspaths the user code
class loader needs to be started with
+ * @return the user code class loader fulfilling the
requirements
+ * @throws IOException if the required jar files cannot be
downloaded
+ * @throws IllegalStateException if the cached user code class
loader does not fulfill the requirements
+ */
+ ClassLoader
getOrResolveClassLoader(Collection<PermanentBlobKey> requiredJarFiles,
Collection<URL> requiredClasspaths) throws IOException;
+ }
/**
- * Shutdown method which may release created class loaders.
+ * Lease which allows to signal when the user code class loader is no
longer needed.
*/
- void shutdown();
+ interface ClassLoaderLease extends ClassLoaderHandle {
- /**
- * True if the LibraryCacheManager has a user code class loader
registered
- * for the given job id.
- *
- * @param jobId identifying the job for which to check the class loader
- * @return true if the user code class loader for the given job has
been registered. Otherwise false.
- */
- boolean hasClassLoader(@Nonnull JobID jobId);
+ /**
+ * Closes the lease to the user code class loader for the
associated job.
+ *
+ * <p>This method signals that the lease holder not longer
needs the user
+ * code class loader for the associated job. Once all leases
for a job a
+ * closed, the library cache manager is allowed to release the
associated
+ * user code class loader.
+ */
+ void close();
Review comment:
I think this is not necessary. Moreover, this method does not need to
throw an exception.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
