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
- Setting the interruptability state allows you to control when cancellation requests sent via the pthread_cancel (BPX1PTB, BPX4PTB) service are handled.
- 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:
- The pthread_testinr service is invoked (BPX1PTI, BPX4PTI).
- A thread is placed in an unbounded wait during a call to a z/OS UNIX service. Some examples of these types of calls
are
- close (BPX1CLO, BPX4CLO) — Close a file
- cond_wait (BPX1CWA, BPX4CWA) — Suspend a thread for an event
- fcntl (BPX1FCT, BPX4FCT) — Control open file descriptors
- open (BPX1OPN, BPX4OPN) — Open a file
- pause (BPX1PAS, BPX4PAS) — Suspend a process pending a signal
- pthread_join (BPX1PTJ, BPX4PTJ) — Wait on a thread
- pthread_testintr (BPX1PTI, BPX4PTI) — Cause a cancellation point to occur
- read (BPX1RED, BPX4RED) — Read from a file or socket
- sigsuspend (BPX1SSU, BPX4SSU) — Change the signal mask and suspend the thread until a signal is delivered
- sigwait (BPX1SWT, BPX4SWT) — Wait for a signal
- sleep (BPX1SLP, BPX4SLP) — Suspend execution of a process for an interval of time
- tcdrain (BPX1TDR, BPX4TDR) — Wait until output has been transmitted
- tcsetattr (BPX1TSA, BPX4TSA) — Set the attributes for a terminal
- wait (BPX1WAT, BPX4WAT) — Wait for a child process to end
- write (BPX1WRT, BPX4WRT) — Write to a file or a socket
- Asynchronous
- Cancellation request can be delivered at any time.
- The default interrupt state for newly created threads and the initial thread is PTHREAD_INTR_ENABLE#.
- The default interrupt type for newly created threads and the initial thread is PTHREAD_INTR_CONTROLLED#.
- 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.
- 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.