FilterHeartbeat Event

Summary

Event for tracking and aborting long-running operations.

Syntax

C++

public event EventHandler<CodecsFilterHeartbeatEventArgs> FilterHeartbeat

Public Event FilterHeartbeat As EventHandler(Of CodecsFilterHeartbeatEventArgs)

public:  
   event EventHandler<CodecsFilterHeartbeatEventArgs^>^ FilterHeartbeat

Event Data

Parameter	Type	Description
sender	object	The source of the event
e	CodecsFilterHeartbeatEventArgs	The event data

Remarks

The RasterCodecs class contains the LoadImage event. It is used to monitor the progress of loading images by calling Load or LoadSvg. The LoadImage event is quite suitable for raster images: the filter (PNG or TIF, for instance), can parse the image file structure quickly and start to send one or more scanlines to the event quickly. Consequently, LoadImage events will start to occur shortly after Load/LoadSvg is called. The application can use LoadImage to show a progress bar to allow the user to monitor and potentially abort the load operation.

The LoadImage event does not work well with complex document file formats such as DOCX and XSLX. Their complex structure requires significantly more time to parse the file structure. The first scanline generated and sent to the LoadImage event may not occur until well after Load/LoadSvg was called. The amount of time required for loading depends on the source file itself. For a very complex document file such as a very large XLSX spreadsheet with thousands or millions of rows, the time can be many seconds or even minutes. Moreover, file structure parsing usually occurs by calling GetInformation (whether called directly by the user, or internally by Load/LoadSvg), none of which invoke the LoadImage event at all.

For complex documents, using the LoadImage event to allow the user to abort long load operations is not feasible: the event will occur at the very end of the operation after all the necessary data has been parsed. A significant amount of time could have elapsed since the original Load/LoadSvg was called. Instead, the application can use the FilterHeartbeat event to monitor and abort very long operations. The FilterHeartbeat event occurs at the beginning of GetInformation, and then again periodically during this function and Load/LoadSvg, allowing the user to abort the current operation if desired.

The FilterHeartbeat event will fire with an instance of CodecsFilterHeartbeatEventArgs, and when CodecsFilterHeartbeatEventArgs.Abort is set to true, RasterCodecs will abort the current operation as follows:

GetInformation will return a CodecsImageInfo object with CodecsImageInfo.Format set to RasterImageFormat.Unknown, and all the rest of the members set to their default values.
Load/LoadSvg will return null instead of a valid RasterImage or ISvgDocument object.

In other words, aborting a filter operation does not throw an exception. Instead, the application should check the returned object as described above to detect when the user aborted.

Some applications require all load operations that take more than a certain time to be aborted (for instance, a web server using LEADTOOLS to load and return images in a web method). This server may require that no operation running within the web method can take more than 2 seconds. When this occurs, the operation should be aborted, and the work delegated to a dedicated thread or process outside of the web service worker thread.

FilterHeartbeat can be used to install an event that tracks the time and aborts all operations taking more than the allocated time. Or, the RasterCodecs.Options.Timeout property can be used to set a global timeout interval for all get information and load operations in a RasterCodecs object. This class uses FilterHeartbeat internally to install a handler that can take care of aborting long-running operations automatically.

Currently filter heartbeat and timeout is only supported for the following file formats:

DOCX/DOC
RTF
TXT
XLSX/XLS

Example

using Leadtools; 
using Leadtools.Codecs; 
using Leadtools.ImageProcessing; 
using Leadtools.ImageProcessing.Color; 
using Leadtools.Svg; 
using LeadtoolsExamples.Common; 
 
// Call this method with a very large and complex XLSX document and a timeout in seconds value 
// Returns true on success and false if aborted 
// For each page, the image is loaded and passed to the processImage action 
public static bool FilterHeartbeatExample(string inputFileName, int timeoutSeconds, Action<RasterImage, int> processImage) 
{ 
   using (var rasterCodecs = new RasterCodecs()) 
   { 
      // This is the start time, we will reset this value 
      // anytime we start an operation 
      DateTime startOperationTime = DateTime.Now; 
 
      // Create a heartbeat handler 
      EventHandler<CodecsFilterHeartbeatEventArgs> heartbeatHandler = (sender, e) => 
      { 
         // Abort if it has been more than timeoutSeconds since last operation 
         TimeSpan timeSpan = DateTime.Now - startOperationTime; 
         if (timeSpan.TotalSeconds > timeoutSeconds) 
         { 
            e.Abort = true; 
         } 
      }; 
 
      // Install the heartbeat handler 
      rasterCodecs.FilterHeartbeat += heartbeatHandler; 
 
      // First, get information on the file to get the number of pages 
      RasterImageFormat format; 
      int pageCount = 0; 
 
      // Reset the start time 
      startOperationTime = DateTime.Now; 
      using (CodecsImageInfo imageInfo = rasterCodecs.GetInformation(inputFileName, true)) 
      { 
         // If GetInformationt took more than timeoutSeconds then we aborted the operation 
         // inside heartbeatHandler and GetInformation will return RasterImageFormat.Unknown 
         format = imageInfo.Format; 
         if (format != RasterImageFormat.Unknown) 
            pageCount = imageInfo.TotalPages; 
      } 
 
      // Did we abort? 
      if (format == RasterImageFormat.Unknown) 
      { 
         // Yes, fail 
         rasterCodecs.FilterHeartbeat -= heartbeatHandler; 
         return false; 
      } 
 
      // Now load all the pages 
 
      for (int pageNumber = 1; pageNumber <= pageCount; pageNumber++) 
      { 
         // Reset the start time 
         startOperationTime = DateTime.Now; 
         RasterImage image = rasterCodecs.Load(inputFileName, pageNumber); 
         // If Load took more than timeoutSeconds then we aborted the operation 
         // inside heartbeatHandler and Load will return null 
 
         // Did we abort? 
         if (image == null) 
         { 
            // Yes, fail 
            rasterCodecs.FilterHeartbeat -= heartbeatHandler; 
            return false; 
         } 
 
         // Process the image and then delete it 
         processImage(image, pageNumber); 
         image.Dispose(); 
      } 
 
      rasterCodecs.FilterHeartbeat -= heartbeatHandler; 
 
      // We successfully loaded and processed all the pages from the file 
      return true; 
   } 
}

Imports Leadtools 
Imports Leadtools.Codecs 
Imports Leadtools.ImageProcessing 
Imports Leadtools.ImageProcessing.Color 
Imports Leadtools.Drawing 
Imports Leadtools.Svg 
 
' Call this method with a very large And complex XLSX document And a timeout in seconds value 
' Returns true on success And false if aborted 
' For each page, the image Is loaded And passed to the processImage action 
Public Shared Function FilterHeartbeatExample(inputFileName As String, timeoutSeconds As Integer, processImage As Action(Of RasterImage, Integer)) As Boolean 
   Using rasterCodecs As New RasterCodecs() 
      ' This Is the start time, we will reset this value 
      ' anytime we start an operation 
      Dim startOperationTime As DateTime = DateTime.Now 
 
      ' Create a heartbeat handler 
      Dim heartbeatHandler As EventHandler(Of CodecsFilterHeartbeatEventArgs) = 
         Sub(sender As Object, e As CodecsFilterHeartbeatEventArgs) 
            ' Abort if it has been more than timeoutSeconds since last operation 
            Dim timeSpan As TimeSpan = DateTime.Now - startOperationTime 
            If timeSpan.TotalSeconds > timeoutSeconds Then 
               e.Abort = True 
            End If 
         End Sub 
 
      ' Install the heartbeat handler 
      AddHandler rasterCodecs.FilterHeartbeat, heartbeatHandler 
 
      ' First, get information on the file to get the number of pages 
      Dim format As RasterImageFormat 
      Dim pageCount As Integer = 0 
 
      ' Reset the start time 
      startOperationTime = DateTime.Now 
      Using imageInfo As CodecsImageInfo = rasterCodecs.GetInformation(inputFileName, True) 
         ' If GetInformationt took more than timeoutSeconds then we aborted the operation 
         ' inside heartbeatHandler And GetInformation will return RasterImageFormat.Unknown 
         format = imageInfo.Format 
         If format <> RasterImageFormat.Unknown Then 
            pageCount = imageInfo.TotalPages 
         End If 
      End Using 
 
      ' Did we abort? 
      If format = RasterImageFormat.Unknown Then 
         ' Yes, fail 
         RemoveHandler rasterCodecs.FilterHeartbeat, heartbeatHandler 
         Return False 
      End If 
 
      ' Now load all the pages 
 
      For pageNumber As Integer = 1 To pageCount 
         ' Reset the start time 
         startOperationTime = DateTime.Now 
         Dim image As RasterImage = rasterCodecs.Load(inputFileName, pageNumber) 
         ' If Load took more than timeoutSeconds then we aborted the operation 
         ' inside heartbeatHandler And Load will return null 
 
         ' Did we abort? 
         If IsNothing(image) Then 
            ' Yes, fail 
            RemoveHandler rasterCodecs.FilterHeartbeat, heartbeatHandler 
            Return False 
         End If 
 
         ' Process the image And then delete it 
         processImage(image, pageNumber) 
         image.Dispose() 
      Next 
 
      RemoveHandler rasterCodecs.FilterHeartbeat, heartbeatHandler 
 
      ' We successfully loaded And processed all the pages from the file 
      Return True 
   End Using 
End Function

Requirements

Target Platforms

Reference

RasterCodecs Class

RasterCodecs Members

Leadtools.Codecs Namespace

Download our FREE evaluation

Help Version 20.0.2020.4.3

Leadtools.Codecs Assembly

Introduction

Getting Started

Namespaces

Leadtools.Codecs Namespace

Assemblies