Skip to main content

By clicking Submit, you agree to the developerWorks terms of use.

The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

  • Close [x]

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerworks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

By clicking Submit, you agree to the developerWorks terms of use.

All information submitted is secure.

  • Close [x]

Fun with DaCS, Part 1: Using an error handler

An example of how to create and register a user error handler

Kane Scarlett, Editor, Multicore acceleration, IBM
Kane Scarlett
Kane Scarlett is a technology journalist/analyst with 20 years in the business, working for such publishers as National Geographic, Population Reference Bureau, Miller Freeman, and IDG, and managing, editing, and writing for such august journals as JavaWorld, LinuxWorld, and of course, developerWorks.

Summary:  In this Cell Broadband Engine™ (Cell/B.E.) series, learn how to create and register a user error handler for use with the Data Communication and Synchronization library (DaCS). The "Data Communication and Synchronization Library for Cell Broadband Engine Programmer’s Guide and API Reference, Version 3.0" (see Resources) is the source for the content.

View more content in this series

Date:  05 Aug 2008
Level:  Introductory PDF:  A4 and Letter (39KB)Get Adobe® Reader®
Also available in:   Japanese

Activity:  22436 views
Comments:  

The Fun with ALF series

Look for more fun in the Fun with ALF series:

And watch for more Fun with series on BLAS and other technologies to make your Cell/B.E. programming easier.

Introduction

This article provides an example that shows how to create and register a DaCS user error handler.

DaCS provides support for registration of user-created error handlers, which are called under certain error conditions. The error handlers can be called for synchronous or asynchronous errors.

In SDK 3.0, any synchronous error reported to the error handlers can cause the process to abort. This happens when DaCS has detected a fatal error from which it cannot recover. Asynchronous errors include child failures (from the host process) and termination requests from a parent (from the accelerator process). Abnormal child termination can cause the parent to abort after calling all registered error handlers.

A normal child exit with a non-zero status can be reported asynchronously to the error handlers, but the process does not abort. This enables the parent process to determine whether the non-zero exit represents an error condition.

When it is called, a user error handler is passed an error object that describes the error, which can be inspected using services provided. The error object contains the DE and PID of the failing process. These can be used to call dacs_de_test() to reap its status and so allow another process to be started on that DE.

The DaCS library uses the SIGTERM signal to handle asynchronous errors and termination requests. A dedicated error handling thread is created in dacs_runtime_init() for this purpose. Applications using the DaCS library should not create any application threads before calling dacs_runtime_init(). No application thread should unmask this signal.

Creating the error handler

Begin by creating a user error handler called my_errhandler. You can use the code in Listing 1.


Listing 1. The error handler

/**************************************************************** 
Example of a user error handler 
This includes invocations of additional functions of 
the passed "dacs_error_t" error parameter 
****************************************************************/ 
int my_errhandler(dacs_error_t error){ 
        /*need local variables for passback of values */ 
        DACS_ERR_T dacs_rc=0; 
        DACS_ERR_T dacs_error_rc;//hold code for error 
        de_id_t de=0; 
        dacs_process_id_t pid=0; 
        uint32_t code = 0; 
        const char * error_string; 

        /* Get the DACS_ERR_T in the error to learn what happened */
printf("\n\n--in my_dacs_errhandler\n"); 
     dacs_error_rc=dacs_rc=dacs_error_num(error); 
     printf(" dacs_error_num indicates DACS_ERR_T=%d %s\n", 
            dacs_rc,dacs_strerror(dacs_rc)); 

     /* Get the exit code in the error to learn what happened */ 
     dacs_rc=dacs_error_code(error,&code); 
     if(dacs_rc){//if error invoking dacs_error_code 
       printf(" dacs_error_code call had error DACS_ERR_T=%d %s\n", 
              dacs_rc,dacs_strerror(dacs_rc)); 
     } 
     else { 
       if (DACS_STS_PROC_ABORTED==dacs_error_rc){ 
           printf(" dacs_error_code signal signal=%d ",code); 
       } 
       else if (DACS_STS_PROC_FAILED==dacs_error_rc){ 
          printf(" dacs_error_code exit code=%d\n",code); 
       } 
       else {//else reason is different than aborted or failed 
          printf(" dacs_error_code exit/signal code=%d\n",code); 
       } 
     } 

     /* Get the error string in the error to learn what happened */ 
     dacs_rc=dacs_error_str(error,&error_string); 
     if(dacs_rc){//if error invoking dacs_error_str 
       printf(" dacs_error_str call had error DACS_ERR_T=%d %s\n", 
              dacs_rc,dacs_strerror(dacs_rc)); 
     } 
     else { 
       printf(" dacs_error_str=%s\n",error_string); 
     } 

     /* Which DE had this error? */ 
     dacs_rc=dacs_error_de(error,&de); 
     if(dacs_rc){//if error invoking dacs_error_de 
       printf(" dacs_error_de call had error DACS_ERR_T=%d %s\n", 
              dacs_rc,dacs_strerror(dacs_rc)); 
     } 
     else { 
       printf(" dacs_error_de=%08x\n",de); 
     } 

     /* What was the dacs_process_id_t? */ 
     dacs_rc=dacs_error_pid(error,&pid); 
     if(dacs_rc){//if error invoking dacs_error_pid 
       printf(" dacs_error_pid call had error" 
              "DACS_ERR_T=%d %s\n",dacs_rc,dacs_strerror(dacs_rc)); 
     } 
     else { 
       printf(" dacs_error_pid=%ld\n",pid); 
     } 
     printf("exiting user error handler\n\n"); 
     return 0;//in SDK 3.0, return value is ignored 
}

Now you register it.


Registering the error handler

You can register the user error handler using the dacs_errhandler_reg API:

dacs_rc= dacs_errhandler_reg((dacs_error_handler_t)&my_errhandler,0);

If the address of my_errhandler is not passed or the cast to dacs_error_handler_t is omitted, the compiler produces warnings.


Reading the error handler output

This is what the output looks like if the accelerator program exits with a return code of 9:

--in my_dacs_errhandler 
  dacs_error_num indicates DACS_ERR_T=4 DACS_STS_PROC_FAILED 
  dacs_error_code exit code=9 
  dacs_error_str=DACS_STS_PROC_FAILED 
  dacs_error_de=01020200 
  dacs_error_pid=5503 
exiting user error handler

This is the example output if the accelerator program aborts:

--in my_dacs_errhandler 
  dacs_error_num indicates DACS_ERR_T=5 DACS_STS_PROC_ABORTED 
  dacs_error_code signal signal=6 
  dacs_error_str=DACS_STS_PROC_ABORTED 
  dacs_error_de=01020200 
  dacs_error_pid=5894 
exiting user error handler


Conclusion

This article provided an example that showed how to create and register a DaCS user error handler.


Resources

Learn

Get products and technologies

Discuss

About the author

Kane Scarlett

Kane Scarlett is a technology journalist/analyst with 20 years in the business, working for such publishers as National Geographic, Population Reference Bureau, Miller Freeman, and IDG, and managing, editing, and writing for such august journals as JavaWorld, LinuxWorld, and of course, developerWorks.

Report abuse help

Report abuse

Thank you. This entry has been flagged for moderator attention.


Report abuse help

Report abuse

Report abuse submission failed. Please try again later.


developerWorks: Sign in


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


Rate this article

Comments

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Multicore acceleration
ArticleID=327354
ArticleTitle=Fun with DaCS, Part 1: Using an error handler
publish-date=08052008
author1-email=kane@us.ibm.com
author1-email-cc=