CodecsTimeoutOptions Class

Summary

Options for the global filter operation timeout used by this RasterCodecs.

Syntax

C++/CLI

Python

public class CodecsTimeoutOptions

public: 
   ref class CodecsTimeoutOptions

class CodecsTimeoutOptions:

Remarks

CodecsTimeoutOptions contains options for the global filter operation timeout used by this RasterCodecs. This class contains the following members:

Member	Description
TimeoutMilliseconds	Timeout value in milliseconds. The default value is 0, meaning there is no timeout set.

The RasterCodecs class contains the LoadImage event that can be used to monitor the progress of loading images using Load or LoadSvg. The LoadImage event is very suitable for raster images since 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. Therefore, LoadImage 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.

For complex document file formats such as DOCX and XSLX, this is not possible. The file filter will require significantly more time to parse the file structure. And the first scanline generated and sent to the LoadImage event may not occur until after a considerable amount of time has passed since Load/LoadSvg was called. This amount of time depends on the source file itself, and for very complex document files such as a very large XLSX spreadsheet with thousands or millions of rows, the time can be in seconds or even minutes.

Moreover, the parsing of the file structure usually occurs during GetInformation (whether called directly by the user or internally by Load/LoadSvg), which does not invoke the LoadImage event at all.

For these kinds of 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 and a significant amount of time could have been elapsed since the original Load/LoadSvg was called.

Instead, the application can use the RasterCodecs.FilterHeartbeat event to monitor and abort these very long operations. This event occurs at the very start of GetInformation and then periodically during this function and Load/LoadSvg to allow the user to abort the current operation if desired.

The 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 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 may have a requirement to abort all load operations that take more than a certain time, (for instance, a web server that uses 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 can be 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 the 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 objects. This class uses [FilterHeartbeat] internally to install a handler that can take care of aborting long-running operations automatically.

For an example on using a heartbeat handler, refer to RasterCodecs.FilterHeartbeat.

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

DOCX/DOC
RTF
TXT
XLSX/XLS

Example

Java

using Leadtools; 
using Leadtools.Codecs; 
using Leadtools.ImageProcessing; 
using Leadtools.ImageProcessing.Color; 
using 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 bool CodecsTimeoutExample(string inputFileName, int timeoutSeconds, Action<RasterImage, int> processImage) 
{ 
   using (var rasterCodecs = new RasterCodecs()) 
   { 
      // Set the timeout 
      // CodecsTimeoutOptions reference 
      rasterCodecs.Options.Timeout.TimeoutMilliseconds = timeoutSeconds * 1000; 
 
      // First, get information on the file to get the number of pages 
      RasterImageFormat format; 
      int pageCount = 0; 
      using (CodecsImageInfo imageInfo = rasterCodecs.GetInformation(inputFileName, true)) 
      { 
         // If GetInformationt took more than timeoutSeconds then RasterCodecs aborted the operation 
         // and GetInformation will return RasterImageFormat.Unknown 
         format = imageInfo.Format; 
         if (format != RasterImageFormat.Unknown) 
            pageCount = imageInfo.TotalPages; 
      } 
 
      // Did we abort? 
      if (format == RasterImageFormat.Unknown) 
      { 
         return false; 
      } 
 
      // Now load all the pages 
 
      for (int pageNumber = 1; pageNumber <= pageCount; pageNumber++) 
      { 
         RasterImage image = rasterCodecs.Load(inputFileName, pageNumber); 
         // If Load took more than timeoutSeconds then RasterCodecs aborted the operation 
         // and Load will return null 
 
         // Did we abort? 
         if (image == null) 
         { 
            // Yes, fail 
            return false; 
         } 
 
         // Process the image and then delete it 
         processImage(image, pageNumber); 
         image.Dispose(); 
      } 
 
      // We successfully loaded and processed all the pages from the file 
      return true; 
   } 
}

 
import java.io.*; 
import java.net.*; 
import java.nio.file.Paths; 
import java.util.*; 
import java.time.Instant; 
import java.time.Duration; 
 
import org.junit.*; 
import org.junit.runner.JUnitCore; 
import org.junit.runner.Result; 
import org.junit.runner.notification.Failure; 
import static org.junit.Assert.*; 
 
import leadtools.*; 
import leadtools.codecs.*; 
import leadtools.codecs.RasterCodecs.FeedCallbackThunk; 
import leadtools.drawing.internal.*; 
import leadtools.imageprocessing.*; 
import leadtools.imageprocessing.color.ChangeIntensityCommand; 
import 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 void codecsTimeoutExample() throws InterruptedException { 
   final String LEAD_VARS_IMAGES_DIR = "C:\\LEADTOOLS23\\Resources\\Images"; 
   String inputFileName = combine(LEAD_VARS_IMAGES_DIR, "leadtools.pdf"); 
   RasterCodecs rasterCodecs = new RasterCodecs(); 
 
   // Set the timeout 
   // CodecsTimeoutOptions reference 
   rasterCodecs.getOptions().getTimeout().setTimeoutMilliseconds(timeoutSeconds * 1000); 
 
   // First, get information on the file to get the number of pages 
   RasterImageFormat format; 
   int pageCount = 0; 
   CodecsImageInfo imageInfo = rasterCodecs.getInformation(inputFileName, true); 
 
   // If GetInformationt took more than timeoutSeconds then RasterCodecs aborted 
   // the operation 
   // and GetInformation will return RasterImageFormat.Unknown 
   format = imageInfo.getFormat(); 
   if (format != RasterImageFormat.UNKNOWN) { 
      pageCount = imageInfo.getTotalPages(); 
   } 
 
   // Did we abort? 
   if (format == RasterImageFormat.UNKNOWN) { 
      return; 
   } 
 
   // Now load all the pages 
   int i = 0; 
   for (int pageNumber = 1; pageNumber <= pageCount; pageNumber++) { 
      i++; 
      RasterImage image = rasterCodecs.load(inputFileName, pageNumber); 
      // If Load took more than timeoutSeconds then RasterCodecs aborted the operation 
      // and Load will return null 
 
      // Did we abort? 
      if (image == null) { 
         // Yes, fail 
         return; 
      } 
 
      // Process the image and then delete it 
      processImage(image, pageNumber); 
      image.dispose(); 
   } 
 
   assertTrue("all pages are accounted for", i == pageCount); 
   System.out.println("all images have been loaded"); 
   // We successfully loaded and processed all the pages from the file 
   return; 
} 
 
public void processImage(RasterImage image, int pageNumber) throws InterruptedException { 
   Thread.sleep(1000); 
}

Requirements

Target Platforms

Reference

CodecsTimeoutOptions Members

Leadtools.Codecs Namespace

Download our FREE evaluation

Help Version 23.0.2024.2.29

Leadtools.Codecs Assembly

Introduction

Getting Started

Namespaces

Leadtools.Codecs Namespace

Assemblies