% MJSFailureInfo Information about a failed task attempt
%
%   parallel.task.MJSFailureInfo properties:
%      Diary           - Text produced by execution of task object's function
%      Error           - Task error information
%      ErrorIdentifier - Task error identifier
%      ErrorMessage    - Message from task error
%      StartDateTime   - Date and time at which this task started running
%      Worker          - Object representing the worker for this task
%      WorkerHost      - Host of the worker for this task
%
%      See also parallel.task.MJSTask

% Copyright 2011-2016 The MathWorks, Inc.

classdef MJSFailureInfo < handle

    properties ( SetAccess = immutable )
        %StartDateTime Date and time at which this task started running
        %   If this task has not started running, StartDateTime is empty.
        %   (read-only)
        StartDateTime

        %ErrorMessage Message from task error
        %   If an error occurs during the task evaluation, ErrorMessage
        %   contains the message property of the MException thrown. If a
        %   worker has crashes during task execution, ErrorMessage contains
        %   information relating the crash. 
        %   (read-only)
        %
        %   ErrorMessage is empty before an attempt to run a task, and
        %   remains empty if the evaluation of a task object function does
        %   not produce an error or if the error did not provide a message.
        %   ErrorMessage has the same value as the message property of the
        %   task's Error.
        %
        %   See also parallel.task.MJSFailureInfo.ErrorIdentifier,
        %            parallel.task.MJSFailureInfo.Error,
        %            parallel.task.MJSTask.Error,
        %            MException.
        ErrorMessage

        %ErrorIdentifier Task error identifier
        %   If an error occurs during the task evaluation, ErrorIdentifier
        %   contains the identifier property of the MException thrown. If a
        %   worker has crashes during task execution, ErrorIdentifier
        %   contains information relating the crash.
        %   (read-only)
        %
        %   ErrorIdentifier is empty before an attempt to run a task, and
        %   remains empty if the evaluation of a task function does not
        %   produce an error or if the error did not provide an identifier.
        %   ErrorIdentifier has the same value as the identifier property
        %   of the task's Error.
        %
        %   See also parallel.task.MJSFailureInfo.ErrorMessage,
        %            parallel.task.MJSFailureInfo.Error,
        %            parallel.task.MJSTask.Error,
        %            MException.
        ErrorIdentifier

        %Error Task error information
        %   The Error property contains an MException, which is empty if no
        %   error occurred.
        %   (read-only)
        %
        %   The Error's message and identifier contain the same information
        %   as the task object properties ErrorMessage and ErrorIdentifier,
        %   respectively.
        %
        %   See also parallel.task.MJSFailureInfo.ErrorIdentifier,
        %            parallel.task.MJSFailureInfo.ErrorMessage,
        %            parallel.task.MJSTask.Error,
        %            MException.
        Error

        %Diary Text produced by execution of task object's function
        %   Diary contains the text produced during the execution of a task
        %   object's Function property that would normally be printed to
        %   the MATLAB Command Window. 
        %   (read-only)
        %
        %   For example, if the function specified in the Function property
        %   makes calls to the disp command, the output that would normally
        %   be printed to the Command Window on the worker is captured in
        %   the Diary property. 
        %
        %   Whether to store the Diary is specified using the CaptureDiary
        %   property. The CaptureDiary property by default is false to save
        %   network bandwidth in situations when the Diary is not needed.
        %
        %   Before a task is evaluated, the default value of Diary is an
        %   empty string.
        %
        %   See also parallel.task.MJSTask.CaptureDiary, 
        %            parallel.task.MJSTask.Function.
        Diary

        %Worker Object representing the worker for this task
        %   The Worker property value is an object representing the worker
        %   session that evaluated the task.
        %   (read-only)
        %
        %   See also parallel.cluster.MJSWorker,
        %            parallel.task.MJSFailureInfo.WorkerHost.
        Worker

        %WorkerHost Host of the worker for this task
        %   The name of the host on which the worker that performed the
        %   task is running.
        %   (read-only)
        %
        %   See also parallel.cluster.MJSWorker,
        %            parallel.task.MJSFailureInfo.Worker.
        WorkerHost
    end

    properties ( Hidden, SetAccess = immutable )
        %StartTime Time at which this task started running
        %   StartTime holds a string specifying the time at which this task
        %   started running, in the format 'ddd mmm dd HH:MM:SS zzz yyyy'.
        %   (read-only)
        %
        %   See also parallel.task.MJSFailureInfo.StartDateTime
        StartTime
    end

    methods ( Access = private )
        function obj = MJSFailureInfo( infoStruct )
            obj.StartDateTime   = infoStruct.StartDateTime;
            obj.StartTime       = infoStruct.StartTime;
            obj.ErrorMessage    = infoStruct.ErrorMessage;
            obj.ErrorIdentifier = infoStruct.ErrorIdentifier;
            obj.Diary           = infoStruct.Diary;
            obj.Worker          = infoStruct.Worker;
            obj.WorkerHost      = infoStruct.WorkerHost;
            if ~isempty( obj.ErrorMessage )
                obj.Error       = MException( obj.ErrorIdentifier, '%s', ...
                                              obj.ErrorMessage );
            else
                % Don't expect to get here
                obj.Error       = MException.empty();
            end
        end
    end

    methods ( Hidden, Static )
        function fai = hBuild( infoStruct )
        % Check correct fields etc.
            fai = parallel.task.MJSFailureInfo( infoStruct );
        end
    end
end
