The arm_end subroutine is used to mark the end of an application. This subroutine call must always be called when a program that issued an arm_init (arm_init Subroutine) subroutine call terminates. In the PTX implementation of ARM, application data structures may persist after arm_end is issued. See Implementation Specifics.
ARM Library (libarm.a).
#include arm.h
arm_ret_stat_t ARM_API arm_end( arm_appl_id_t appl_id, /* application id
*/
arm_flag_t flags, /* Reserved = 0 */
arm_data_t *data, /* Reserved = NULL */
arm_data_sz_t data_size); /* Reserved = 0 */
By calling the arm_end subroutine, an application program signals to the ARM library that it has ceased issuing ARM subroutine calls for the application specified and that the library code can remove references to the application. As far as the calling program is concerned, all references to transactions defined for the named application can be removed as well.
The identifier is returned by an earlier call to arm_init, arm_init Subroutine. The PTX implementation does not require that the arm_init subroutine call was issued by the same program or process now issuing the arm_end subroutine call. However, each time the arm_end subroutine call is issued against an appl_id, the use-count of the transaction structure is decremented. When the count reaches zero, the application structure and all associated transaction structures are marked as inactive. Subsequent arm_init calls can reactivate the application structure but transaction structures formerly associated with the application are not automatically activated. Each transaction must be reactivated through the arm_getid (arm_getid Subroutine) subroutine call.
The appl_id is used to look for an application structure. If none is found, no action is taken and the function returns -1. If one is found, the use-count of the application structure is decremented. If that makes the counter zero, the use-counts of all associated transaction structures are set to zero. The total number of application structures that have been initialized for the calling process but not ended is decremented. If this count reaches zero, access to the shared memory from the process is released and the count of users of the shared memory area is decremented. If the count of users of the shared memory segment reaches zero, the shared memory segment is deleted.
In the current API definition, the last three arguments are for future use and they are ignored in the implementation.
If successful, the subroutine returns zero. If the subroutine fails, a value less than zero is returned.
No error codes are defined by the PTX implementation of the ARM API.
This subroutine is part of the implementation of the ARM API in the Performance Toolbox for AIX licensed product.
Note that, in the PTX implementation of ARM, multiple processes can issue arm_init (arm_init Subroutine) subroutine calls for a given application with the effect that multiple simultaneous definitions of the application are effective. The ARM library code points all these definitions to a single application structure in the ARM private shared memory area. A use-count keeps track of the number of simultaneous definitions. Each time arm_init is issued for the application name, the counter is incremented and each time the arm_end subroutine call is issued for the associated appl_id, the counter is decremented. No call to arm_end is permitted to decrement the counter less than zero.
Only when the counter reaches zero is the application structure inactivated. As long as the counter is non-zero, transactions defined for the application remain active and new transactions can be defined for the application. It does not matter which process created the definition of the application.
This implementation was chosen because it makes perfect sense in a PTX environment. Any more restrictive implementation would have increased memory use significantly and would be useless for PTX monitoring purposes.
| /usr/include/arm.h | Declares the subroutines, data structures, handles, and macros that an application program can use to access the ARM library. |
***, arm_init (arm_init Subroutine) subroutine, arm_getid (arm_getid Subroutine) subroutine.