LAPI_Purge_totask Subroutine

Purpose

Allows a task to cancel messages to a given destination.

Library

Availability Library (liblapi_r.a)

C Syntax

#include <lapi.h>
 
int LAPI_Purge_totask(hndl, dest)
lapi_handle_t hndl;
uint          dest; 

FORTRAN Syntax

include 'lapif.h'
 
int LAPI_PURGE_TOTASK(hndl, dest, ierror)
INTEGER hndl
INTEGER dest
INTEGER ierror

Description

Type of call: recovery

This subroutine cancels messages and resets the state corresponding to messages in flight or submitted to be sent to a particular target task. This is an entirely local operation. For correct behavior a similar invocation is expected on the destination (if it exists). This function cleans up all the state associated with pending messages to the indicated target task. It is assumed that before the indicated task starts communicating with this task again, it also purges this instance (or that it was terminated and initialized again). It will also wake up all threads that are in LAPI_Nopoll_wait depending on how the arguments are passed to the LAPI_Nopoll_wait function. The behavior of LAPI_Purge_totask is undefined if LAPI collective functions are used.

Note: This subroutine should not be used when the parallel application is running in a PE/LoadLeveler environment.

LAPI_Purge_totask is normally used after connectivity has been lost between two tasks. If connectivity is restored, the tasks can restored for LAPI communication by calling LAPI_Resume_totask.

Parameters

INPUT

hndl

Specifies the LAPI handle.

dest

Specifies the destination instance ID to which pending messages need to be cancelled.

OUTPUT

ierror

Specifies a FORTRAN return code. This is always the last parameter.

Restrictions

Use of this subroutine is not recommended on a system that is running Parallel Environment (PE).

Return Values

LAPI_SUCCESS

Indicates that the function call completed successfully.

LAPI_ERR_HNDL_INVALID

Indicates that the hndl passed in is not valid (not initialized or in terminated state).

LAPI_ERR_TGT

Indicates that dest is outside the range of tasks defined in the job.

Location

/usr/lib/liblapi_r.a