%ISession Interface to a parallel.Pool session implementation.
%   Implementations of ISession

% Copyright 2020-2021 The MathWorks, Inc.

classdef (Abstract) ISession < handle
    % Methods needed by the parallel.Pool object - mostly meta-data about the pool
    % session itself.
    methods (Abstract, Access = {?parallel.internal.pool.AbstractClusterPool, ...
                            ?parallel.internal.pool.ISession})
        uuid = getSessionUUID(obj);
        tf = canInitializeSpmd(obj);
        tf = initializeSpmd(obj);
        fq = getFevalQueue(obj, pool);
    end

    % Needed by ticBytes/tocBytes
    methods (Abstract, Access = {?parallel.pool.TicBytesResult, ...
                            ?parallel.internal.pool.ISession})
        info = getCurrentBytesTransferredToInstances(obj);
    end

    % Setup/teardown methods needed by the pool "client" object.
    methods (Abstract, Access = {?parallel.internal.pool.AbstractClient, ...
                            ?parallel.internal.pool.ISession})
        tf = destroyClientSession(obj);
        startSendPathAndClearNotificationToLabs(obj);
        waitForConnections(obj, spmdInitialized, sessionInfo, checkFcn)
        tf = waitForSessionToStart(obj, timeInSeconds);
    end

    % Worker-only methods
    methods (Abstract, Access = {?parallel.internal.pool.AbstractWorker, ...
                            ?parallel.internal.pool.ISession})
        setDependencyDir(obj, dependencyDir);
    end
    
    % These methods are accessed outside class scope, and so cannot have access
    % constraints.
    methods (Abstract)
        % Required by mpiprofile
        evalOnClient(obj, cmd);

        % Environment / files etc.
        fda = getFileDependenciesAssistant(obj);

        % Used by pmode.m and AbstractClusterPool.
        n = getPoolSize(obj);

        % Startup and shutdown
        tf = isSessionRunning(obj);
        % Mostly used by AbstractClusterPool, but also by tests
        setRestartOnClusterChange(obj, tf);
        setShutdownIdleTimeout(obj, timeInSeconds);
        info = getClientSessionInfo(obj);
        
        % Used by pctPreRemoteEvaluation
        % Rehashes MATLAB if this session has been marked as needing it.
        % NB: Returns whether a rehash occurred for testing purposes only
        rehashed = rehashIfNecessary(obj);
        
        % Used by parallel.internal.pool.clearFunction
        % Removes and returns all items that have been collected by the
        % session for clearing on the worker
        itemsToClear = drainItemsToClear(obj, varargin);

        % Parallel language - parfor
        releaseCurrentParforController(obj);
        futureController = createParforController(obj, maxBacklog, maxNumWorkers);
        % Parallel language - spmd
        ctrl = createSpmdController(obj, labIndices);
        assistant = getCompositeAssistant(obj, labIndices);
        map = getCompositeKeysToClearMap(obj);
        % Parallel language - DataQueue
        factory = createRemoteQueueFactory(obj, queueUuid)
        
        shutdown(obj);
    end
end
