pthread_setintr (BPX1PSI, BPX4PSI) — Examine and change the interrupt state

Function

The pthread_setintr callable service sets the specified interruptability state of the calling thread and atomically returns the previous interruptability state.

Requirements

Operation Environment
Authorization: Supervisor state or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE: 31-bit
ASC mode: Primary mode
Interrupt status: Enabled for interrupts
Locks: Unlocked
Control parameters: All parameters must be addressable by the caller and in the primary address space.

Format

The syntax format is as follows:
CALL BPX1PSI,(Interrupt_state,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4PSI with the same parameter.

Parameters

Interrupt_state
Supplied parameter
Type:
Structure
Length:
Fullword
Specifies the name of a fullword that contains a numeric value that identifies the interrupt state that is to be set. The following constants, which are defined in the BPXYCONS macro, define the valid states (see BPXYCONS — Constants used by services):
Constant Description
PTHREAD_INTR_ENABLE# When interruptability is enabled, new or pending cancellation requests are acted upon according to the interruptability type set by the pthread_setintrtype service (BPX1PST, BPX4PST).
PTHREAD_INTR_DISABLE# When interruptability is disabled, cancellation requests against the target thread are held pending.
Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the service returns the previous interrupt state, or -1 if the service did not complete successfully.

Return_code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the pthread_setintr service stores the return code. The pthread_setintr service returns Return_code only if Return_value is -1. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. The pthread_setintr service can return the following value in the Return_code parameter:
Return code Explanation
EINVAL One of the parameters contains a value that is not valid.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the pthread_setintr service stores the reason code. The pthread_setintr service returns Reason_code only if Return_value is -1. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.

Usage notes

  1. Setting the interruptability state allows you to control when cancellation requests sent via the pthread_cancel (BPX1PTB, BPX4PTB) service are handled.
  2. The pthread_setintr (BPX1PSI, BPX4PSI) and pthread_intrtype (BPX1PST, BPX4PST) services establish three interruptability states:
    Disabled
    Cancellation requests are left pending.
    Controlled
    Cancellation requests are left pending until the next cancellation point is reached. Cancellation points are defined as when:
    Asynchronous
    Cancellation request can be delivered at any time.
  3. The default interrupt state for newly created threads and the initial thread is PTHREAD_INTR_ENABLE#.
  4. The default interrupt type for newly created threads and the initial thread is PTHREAD_INTR_CONTROLLED#.
  5. The interruption types of controlled and asynchronous are set with pthread_intrtype (BPX1PST, BPX4PST). See pthread_setintrtype (BPX1PST, BPX4PST) — Examine and change the interrupt type. These states are acted upon only if thread interruption is enabled. If a cancellation request is pending and the interrupt state or type is set to allow asynchronous cancellation requests, the thread is canceled before control is returned to the invoker.
  6. See Optimizing performance using process- and thread-level information.

Related services

Characteristics and restrictions

There are no restrictions on the use of the pthread_setintr service.

Examples

See BPX1PSI (pthread_setintr) example.