MULTICS TECHNICAL BULLETIN MTB-753, Revision 2
To: MTB Distribution
From: Gary M. Palter & Stan Cox
Date: 10 July 1986
Subject: Multiplexing Control Points in a Process
ABSTRACT
This MTB proposes changes to support simple user ring tasking.
Control points are sub-process entities whose execution can be
interleaved. The proposal includes general descriptions of
commands and subroutines to manipulate tasks, and changes to the
system to deal with the more complex environment.
Comments should be sent:
via Forum:
>udd>m>mtgs>control_point_management (cpm_) on System-M
_________________________________________________________________
Multics Project internal working documentation. Not to be
distributed outside the project without the consent of the author
or the Director of Multics System Development.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
CONTENTS
Page
Reason . . . . . . . . . . . . . . . 2
Solution . . . . . . . . . . . . . . 2
Example . . . . . . . . . . . . . 3
Creating the Listen Control Point 3
Destroying the Listen Control
Point . . . . . . . . . . . . . . 4
Creating a Control Point for each
Connection Request . . . . . . . 4
Control Within Each Control Point 4
Implementation . . . . . . . . . . . 4
Multiple control points . . . . 6
Example . . . . . . . . . . . . . 6
Documentation . . . . . . . . . . . . 7
Appendix A Changes to Existing Subroutines . . . . A-1
ipc_ . . . . . . . . . . . . . . . A-2
reassign_call_channels . . . . A-2
wait_for_an_event . . . . . . . A-2
Appendix B Changes to Existing Structures . . . . . B-1
Appendix C Commands . . . . . . . . . . . . . . . . C-1
control_point_manager_call . . . . C-2
cl_intermediary . . . . . . . . C-3
create . . . . . . . . . . . . C-3
destroy . . . . . . . . . . . . C-6
enable . . . . . . . . . . . . C-6
enabled . . . . . . . . . . . . C-7
generate_call . . . . . . . . . C-7
id . . . . . . . . . . . . . . C-8
list . . . . . . . . . . . . . C-9
pop_preferred . . . . . . . . . C-10
preferred . . . . . . . . . . . C-10
probe . . . . . . . . . . . . . C-11
program_interrupt . . . . . . . C-12
push_preferred . . . . . . . . C-12
run . . . . . . . . . . . . . . C-13
scheduler . . . . . . . . . . . C-16
select . . . . . . . . . . . . C-16
set_cl_intermediary . . . . . . C-17
set_preferred . . . . . . . . . C-18
start . . . . . . . . . . . . . C-18
stop . . . . . . . . . . . . . C-19
wakeup . . . . . . . . . . . . C-19
Appendix D Subroutines . . . . . . . . . . . . . . D-1
cpm_ . . . . . . . . . . . . . . . D-2
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
Page
block . . . . . . . . . . . . . D-2
create . . . . . . . . . . . . D-2
destroy . . . . . . . . . . . . D-6
generate_call . . . . . . . . . D-7
generate_call_preferred . . . . D-8
generate_call_when_ready . . . D-9
get_control_point_meters . . . D-10
get_preferred_control_point . . D-11
get_scheduler_meters . . . . . D-12
get_user_cl_intermediary . . . D-14
pop_preferred_control_point . . D-15
push_preferred_control_point . D-15
scheduler . . . . . . . . . . . D-17
set_preferred_control_point . . D-17
set_user_cl_intermediary . . . D-18
start . . . . . . . . . . . . . D-19
stop . . . . . . . . . . . . . D-20
wakeup . . . . . . . . . . . . D-21
cpm_data_ . . . . . . . . . . . . D-23
n_control_points . . . . . . . D-23
get_control_point_id_ . . . . . . D-24
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
REASON
A task can be thought of as a set of independent states in a
process. Each task can be defined by its ability to:
o have its own stack
o optionally have its own LOT
o optionally have its own ISOT
o optionally have its own RNT
o optionally have its own user free area
o optionally have its own IO switches
o have its own ips_mask
o have its own cl_intermediary
The target applications for control point management are
restricted environments such as network servers. In a
well-defined environment such as this, each task will not require
its own RNT, LOT, ISOT, and user free area. This is because each
task does not require that it be able to manage its own namespace
in the limited environment that it runs in. We define a control
point as a simple task, having its own stack, but sharing the
namespace and static variables of the primary (or root) task.
SOLUTION
The control point manager provides a simple form of multitasking
within a process. Each task can be in a given state as indicated
by the directed graph in figure 1.
A queue of ready control points is maintained by the control
point scheduler to determine which control point to run. A stack
of preferred control points is also taken into account, in case a
ready control point should be given a higher priority. Each
control point has its own stack, and each stack has a pointer to
the control_point_data structure for that control point. The
control_point_data structure contains the control point specific
information including priority, state, IO switch pointers,
ips_mask, and system privilege. It also contains links to the
previous and next child and sibling control points (if any).
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
___________ $start ___________
$create | |------------------>| |
--------->| stopped | $stop | ready |
| | |<------------------| |
| |_________| |------------>|_________|
| |^ | $wakeup_____|_____|^ |
| | | | | |
___________ | | | | _____|
| deleted | | ------|---- | | |
| or | -----| | | | | $schedule
|^existant| $stop| blocked |<--| | | OR
|_________| |_________|$block | | ipc_
^| |^ | v
| ___________ |___________|_________
| | | ipc_ | |
----------|destroyed| $destroy | running |
|_________|<------------------|_________|
Figure 1. Task State Digraph
Example
The following example is an example from the DSA login server,
which is responsible for managing user requests for access to
Multics from communications channels managed by the login server.
The login server creates a control point which listens to the
endpoint, and creates a control point for each connection request
that comes in.
Creating the Listen Control Point
create_control_point_info.version =
CREATE_CONTROL_POINT_INFO_VERSION_1;
create_control_point_info.comment = rtrim ("listening");
create_control_point_info.initproc.entry = login_server_$listen;
create_control_point_info.initproc.info_ptr = ls_listen_info_ptr;
create_control_point_info.priority = 1;
string (create_control_point_info.flags) = ""b;
create_control_point_info.independent = "1"b;
create_control_point_info.header.pad = "0"b;
call cpm_$create (ccpi_ptr, control_point_id, code);
call cpm_$start (control_point_id, code);
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
Destroying the Listen Control Point
call cpm_$destroy (control_point_id, code);
Creating a Control Point for each Connection Request
create_control_point_info.version =
CREATE_CONTROL_POINT_INFO_VERSION_1;
create_control_point_info.comment = "login dialogue";
create_control_point_info.initproc.entry =
login_server_connection_;
create_control_point_info.initproc.info_ptr = ls_cp_info_ptr;
create_control_point_info.priority = 1;
string (create_control_point_info.flags) = ""b;
create_control_point_info.independent = "1"b;
if attach_description ^= ""
then do; /* allow for varying attach descriptions */
create_control_point_info.separate_standard_iocbs = "1"b;
create_control_point_info.user_io_attach_desc_given = "1"b;
end;
create_control_point_info.header.pad = ""b;
create_control_point_info.user_io_attach_desc =
attach_description;
call cpm_$create (ccpi_ptr, control_point_id, code);
call cpm_$start (control_point_id, code);
Control Within Each Control Point
The code for a control point has no control point management
specific calls. It simply calls ipc_ entries in the normal way.
For instance in the above example, login_server_connection_ will:
engage in the login dialogue between the user and the
Initializer, set up disconnect and process termination handlers,
and wake up the user process.
IMPLEMENTATION
The control point id is the segment number of the stack for that
control point. The data segment, cpm_data_, contains a bit map,
indexed by segment number, indicating if a segment is a stack for
a live control point.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
Creating a control point creates its stack, initializes its
control_point_data structure and adds its stack segment number to
the bit map in cpm_data_. The created control point is initially
in the stopped state. A temporary segment is obtained to use as
the control point's stack. The control point's stack is copied
from the parent, then the stack_begin_ptr, stack_end_ptr, and
control point_data_ptr are modified. The id of the control point
is the segment number of the temporary segment with unique_bits
in the least significant bits.
Starting a control point changes its state in control_point_data
and adds that control point to the ready queue. The ready queue
is a queue of pointers to control_point_data structures.
The control point scheduler determines which ready control point
is put into the running state by picking the preferred control
point, or if there is no preferred control point, the first
control point in the ready queue. A stack frame is created on
the new stack containing the entry point to an alm routine
(cpm_alm_$call_overseer) to be returned to. When a different
control point is run the stacks of the current control point and
the selected control point are switched by calling
cpm_alm_$switch_stack. When cpm_alm_$call_overseer is "returned
to" it calls a pl1 routine, cpm_overseer_, which sets up the
cl_intermediary to cpd.cl_intermediary and creates separate IO
switches, if needed, for the new control point. It then calls
cu_$generate_call to call the entrypoint specified by the user.
When the user routine completes execution, it returns to
cpm_overseer, which returns to cpm_alm_$call_overseer, which
calls cpm_$self_destruct to kill the control point and call the
scheduler.
If a control point calls ipc_$block, then that control point is
put in the blocked state by ipc_ (which calls cpm_$block). When
a wakeup occurs for a control point, it is put into the ready
state by ipc_ (which calls cpm_$wakeup). The next available
control point is scheduled by calling cpm_$schedule. If
cpm_$schedule has nothing to run, it calls
ipc_$wait_for_an_event, which waits for any ipc event to occur,
and then notifies the waiting control point. A user program will
not typically block and schedule control points itself. The ipc_
facility is the primary caller of cpm_$block, cpm_$wakeup, and
cpm_$schedule.
The entry point cpm_$destroy destroys a control point by having
the control point do a non-local goto to the label
cpm_$self_destruct, which changes the state of this control point
to destroyed and calls the control point scheduler.
The scheduler periodically garbage collects destroyed control
points by destroying the stack and control_point_data for the
given control point and all of its children.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
MULTIPLE CONTROL POINTS
There can only be one control point associated with an event call
channel, but there can be multiple control points associated with
an event wait channel. If there are multiple control points
blocked on the same event, then the one with the highest priority
will run first. When the others are run, they will try to read
the message, but it will be gone and they will go blocked again.
The control point to be run next can be made the preferred
control point so it will be run when it is ready.
Example
The following example traces the calls to ipc_ and cpm. It
assumes a program, get_input, is running in control point 245,
and is looping getting input from the user_input switch. A
program, wait_for_wakeup, is running in control point 300, and is
waiting for a wakeup.
The program get_input calls iox_$get_line which calls
ipc_real_$full_block, which checks stack_header.cpm_enabled to
see if there is more than one control point defined in the
process. If there is more than one control point then
get_control_point_id_ is called to get the current control point,
and add_to_waiting_lists is called to add the control point to
the list of control points waiting for an event. Then the
internal procedure block_if_no_pending_events is called. It
first checks the event_wait_list (input parameter to ipc_$block)
to see if any events are pending. If there are none, then all
call channels are checked to see if they are owned by the current
control point and have pending events. In this example there are
no pending events for the current control point, so we enter the
blocked state by calling cpm_$block.
The entry cpm_$block marks the current control point as being
blocked, and control returns to ipc_real_$full_block which calls
cpm_$scheduler to find another control point to run. There are
no other control points which can be scheduled, since
wait_for_wakeup in the other control point has not yet received
its wakeup, so ipc_real_$wait_for_an_event is called. When an
event arrives the internal procedure
wakeup_blocked_control_points is called, to check all wait and
call channels. If an event wait channel has control points to be
woken up, then the waiting_control_point list is run through and
cpm_$wakeup is called to change the state of the control point to
ready. If a message has arrived for an event call channel, then
cpm_$wakeup is called for the control point which owns the
channel to change its state to ready. When
wakeup_blocked_control_points returns, control returns to
cpm_$scheduler, which returns to ipc, which returns to tty_ to
get the input line.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
If the control point running get_input is blocked waiting for
input and a wakeup arrives for the waiting_for_wakeup program
which is running in the other control point, then the following
occurs. The entry ipc_real_$full_block calls
block_if_no_pending_events, which blocks the current control
point. Control returns to ipc_real_$full_block which calls the
internal procedure wakeup_blocked_control points. This internal
procedure calls cpm_$wakeup to change the state of the control
point running waiting_for_wakeup. The full_block entry then
calls cpm_$scheduler which switches to the other control point
which received the wakeup.
DOCUMENTATION
The remainder of this MTB consists of the Commands Manual
writeup for control_point_manager_call, and the Subroutines
Manual writeups for cpm_, cpm_data_, and get_control_point_id_,
all of which will be bound together as bound_cpm_ and installed
in >system_library_tools. The changes made to ipc_ to support
control point management are also described. The
control_point_manager_call command, and the subroutines cpm_, and
get_control_point_id_ are to be considered internal interfaces.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
APPENDIX A
CHANGES TO EXISTING SUBROUTINES
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
ipc_ ipc_
____ ____
Name: ipc_
________________________________________
Entry: ipc_$reassign_call_channels
This entrypoint reassigns call channels from one control
point to another one whenever a control point is destroyed.
USAGE
dcl ipc_$reassign_call_channels entry (bit (36) aligned,
bit (36) aligned);
call ipc_$reassign_call_channels (old_control_point_id,
new_control_point_id);
ARGUMENTS
old_control_point_id
(Input)
is the unique ID of the control point to be destroyed.
new_control_point_id
is the unique ID of the control point to be assigned
the event call channel.
________________________________________
Entry: ipc_$wait_for_an_event
Wait for an ipc_ event when there are no control points in
the ready states.
USAGE
dcl ipc_$wait_for_an_event entry ();
call ipc_$wait_for_an_event ();
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
ipc_ ipc_
____ ____
NOTES
The arrival of an event will cause the control point waiting
for that event to be put into the ready state.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
APPENDIX B
CHANGES TO EXISTING STRUCTURES
Changes to ect_structures.incl.pl1
dcl 1 waiting_control_point
aligned based (wcpp),
2 word_0,
3 block_count
fixed bin (17) unal,
3 type fixed bin (17) unal,
2 control_point_id
bit (36) aligned,
2 chain,
3 next_wcpp pointer,
3 prev_wcpp pointer,
where:
block_count
is the number of ipc_$block calls made by the control
point
type is the type of waiting control point (currently not
used).
control_point_id
is the id of the waiting control point
next_wcpp is a pointer to the next waiting control point.
prev_wcpp is a pointer to the previous waiting control point.
o The structure wait_channel has the following added:
dcl 1 wait_channel aligned based (ectep),
2 word_0,
3 unused1 fixed bin (17) unal,
3 type fixed bin (17) unal,
2 next_chanp ptr unal,
2 prev_chanp ptr unal,
2 word_3,
3 fast_channel
bit (1) unal,
3 inhibit_count
fixed bin (16) unal,
3 wakeup_control_points
bit (1) unal,
3 wakeup_count
fixed bin (17) unal unsigned,
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
2 name bit (72),
2 first_ev_msgp
ptr unal,
2 last_ev_msgp
ptr unal,
2 first_wcpp ptr unal,
2 last_wcpp ptr unal,
2 fast_channel_id
fixed binary,
2 unused2 fixed bin;
where:
wakeup_control_points
indicates the control point waiting on this channel
should be woken up.
first_wcpp
is the pointer to the first control point waiting on
this channel. See the description of the
waiting_control_point structure above.
last_wcpp is the pointer to the last control point waiting on
this channel. See the description of the
waiting_control_point structure above.
o The structure call_channel has the following added:
dcl 1 call_channel aligned based (ectep),
2 word_0,
3 priority fixed bin (17) unal,
3 type fixed bin (17) unal,
2 next_chanp ptr unal,
2 prev_chanp ptr unal,
2 word_3,
3 call_inhibit
bit (1) unal,
3 inhibit_count
fixed bin (16) unal,
3 wakeup_control_points
bit (1) unal,
3 wakeup_count
fixed bin (18) unal unsigned,
2 name bit (72),
2 first_ev_msgp
ptr unal,
2 last_ev_msgp
ptr unal,
2 data_ptr ptr unal,
2 procedure_value,
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
3 procedure_ptr
ptr unal,
3 environment_ptr
ptr,
2 control_point_id
bit (36) al;
where:
wakeup_control_points
indicates the control point waiting on this channel
should be woken up.
control_point_id
is the control point which owns this channel
o The following was added to the stack_header:
dcl 1 stack_header based (sb) aligned,
2 pad1 (4) fixed bin,
2 old_lot_ptr ptr,
2 combined_stat_ptr
ptr,
2 clr_ptr ptr,
2 max_lot_size
fixed bin (17) unal,
2 main_proc_invoked
fixed bin (11) unal,
2 have_static_vlas
bit (1) unal,
2 pad4 bit (2) unal,
2 run_unit_depth
fixed bin (2) unal,
2 cur_lot_size
fixed bin (17) unal,
2 pad2 bit (18) unal,
2 system_free_ptr
ptr,
2 user_free_ptr
ptr,
2 null_ptr ptr,
2 stack_begin_ptr
ptr,
2 stack_end_ptr
ptr,
2 lot_ptr ptr,
2 signal_ptr ptr,
2 bar_mode_sp ptr,
2 pl1_operators_ptr
ptr,
2 call_op_ptr ptr,
2 push_op_ptr ptr,
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
2 return_op_ptr
ptr,
2 return_no_pop_op_ptr
ptr,
2 entry_op_ptr
ptr,
2 trans_op_tv_ptr
ptr,
2 isot_ptr ptr,
2 sct_ptr ptr,
2 unwinder_ptr
ptr,
2 sys_link_info_ptr
ptr,
2 rnt_ptr ptr,
2 ect_ptr ptr,
2 assign_linkage_ptr
ptr,
2 cpd_ptr ptr unaligned,
2 cpm_enabled bit (36),
2 trace,
3 frames,
4 count, fixed bin,
4 top_ptr ptr unal,
3 in_trace bit (36) aligned,
2 pad3 (3) bit (36) aligned;
where:
cpd_ptr is a pointer to the control_point_data structure for
the control point which owns this stack if control
point management is enabled.
cpm_enabled
is set to control_point_data.id of the control point
for which this is a stack if control point management
is enabled, and is "0" otherwise.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
APPENDIX C
COMMANDS
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
Name: control_point_manager_call, cpmc
This command is the command level interface to the control
point management facility.
SYNTAX AS A COMMAND
cpmc operation {arguments} {-control_args}
SYNTAX AS AN ACTIVE FUNCTION
[cpmc operation {arguments}]
ARGUMENTS
operation identifies the operation to be performed by this
invocation of control_point_manager_call. Detailed
descriptions of the supported operations follow.
arguments
-control_args
are specific to the requested operation and are
described below.
NOTES
Many of the operations described below act on an arbitrary
control point as opposed to the current control point. The
desired control point is selected by supplying the operation with
the control point's unique ID. A control point's unique ID is a
12 digit octal value which is displayed by this command's list
operation. In addition, the list operation also displays a 6
digit short form of the ID which may also be used to select the
control point. When using either form of the control point's
unique ID, leading zeroes may be omitted
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
control_point_manager_call Operation: cl_intermediary
This operation returns or displays the identity of the user
supplied command level intermediary for the specified control
point.
SYNTAX AS AN ACTIVE FUNCTION
[cpmc cl_intermediary ID]
SYNTAX AS A COMMAND
cpmc cl_intermediary ID
ARGUMENTS
ID is the unique ID of the desired control point.
NOTES
When used as an active function, this operation returns the
identity of the command level intermediary in a form suitable for
use with the set_cl_intermediary operation described below.
________________________________________
control_point_manager_call Operation: create, cr
This operation creates a new control point.
SYNTAX
cpmc cr ENTRY {INFO_PTR} {-control_args}
ARGUMENTS
ENTRY is the initial procedure to be run in the new control
point. ENTRY is a virtual entrypoint as accepted by
the cv_entry_ subroutine.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
INFO_PTR is a pointer which is passed as the single argument to
the new control point's initial procedure. INFO_PTR is
a virtual pointer as accepted by the cv_ptr_
subroutine. If no INFO_PTR is specified, a null
pointer is passed to the initial procedure.
CONTROL ARGUMENTS
-long, -lg
displays a message giving the ID of the newly created
control point. (Default)
-brief, -bf
does not display the message described above.
-start, -sr
marks the new control point as ready for execution.
Actual execution of the control point will begin when
all higher priority control points in the process are
blocked waiting for an IPC wakeup.
-no_start, -nsr
does not mark the new control point as ready for
execution. (Default)
-preferred
makes the new control point the preferred control
point. This control argument may not be specified
unless "-start" is also specified.
-not_preferred
does not make the new control point the preferred
control point. (Default)
-priority N
sets the scheduling priority of the new control point
to N which must be an integer. A ready control point
whose priority is 1 is always scheduled before any
ready control point whose priority is 2, etc. The
default priority is 1.
-comment STR, -com STR
specifies a description of the new control point which
will be displayed by the list operation The default
description is the name of the control point's initial
procedure.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
-independent
specifies that the new control point will be
independent of all other control points in the process.
At present, the independence of a control point only
affects when the storage it has used will be released
after it is destroyed. (Default)
-dependent
specifies that the new control point will be a child of
the current control point.
-cl_intermediary ENTRY
specifies the entrypoint to be used as the command
level intermediary for the new control point. ENTRY is
a virtual entrypoint as accepted by the cv_entry_
subroutine.
-default_cl_intermediary
specifies that the new control point is to used the
standard command level intermediary provided by the
control point manager. (Default)
-separate_io_switches {STR}, -sepios {STR}
specifies that the new control point is to have its own
set of standard I/O switches (i.e., user_i/o,
user_input, user_output, and error_output). If STR is
supplied, it is the attach description for the new
control point's user_i/o switch. If STR is not
supplied, its user_i/o will be attached via the syn_
I/O module to the current control point's user_i/o. In
either case, the actual attachment of the I/O switches
will be performed in the new control point before its
initial procedure is invoked.
-shared_io_switches, -shios
specifies that the new control point is to use the same
set of standard I/O switches as the current control
point (Default)
NOTES
The run operation, described below, is the preferred method
to execute a command line in a control point.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
control_point_manager_call Operation: destroy
This operation destroys the specified control point.
SYNTAX
cpmc destroy ID
ARGUMENTS
ID is the unique ID of the control point to be destroyed.
NOTES
When a control point is destroyed, the cleanup handlers of
all entrypoints still active in the control point are run, the
control point's standard I/O switches are detached, and the
storage used by its stack is released.
________________________________________
control_point_manager_call Operation: enable, invoke
This operation enables control point management.
SYNTAX
cpmc enable
NOTES
Control point management is enabled automatically by the first
use of this command's create or run operations or by the first
call to the cpm_$create entrypoint.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
control_point_manager_call Operation: enabled, invoked
This operation returns "true" if control point management is
already enabled in the process and "false" otherwise.
SYNTAX AS AN ACTIVE FUNCTION
[cpmc enabled]
SYNTAX AS A COMMAND
cpmc enabled
________________________________________
control_point_manager_call Operation: generate_call, gc
This operation queues a call to an arbitrary entrypoint in a
specific control point and, optionally, forces the immediate
execution of said call.
SYNTAX
cpmc gc ID ENTRY {INFO_PTR} {-control_args}
ARGUMENTS
ID is the unique ID of the control point in which the
entrypoint is to be run.
ENTRY identifies the entrypoint to be run. ENTRY is a
virtual entrypoint as accepted by the cv_entry_
subroutine.
INFO_PTR is a pointer which is passed as the single argument to
the above entrypoint. INFO_PTR is a virtual pointer as
accepted by the cv_ptr_ subroutine. If no INFO_PTR is
specified, a null pointer is passed to the entrypoint.
CONTROL ARGUMENTS
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
-immediate, -im
specifies that execution of the entrypoint is to take
place immediately. (Default)
-defer_until_ready, -dur
specifies that execution of the entrypoint is not to
occur until the control point is next ready for
execution and is subsequently selected for execution by
the control point scheduler. If the control point is
already ready for execution, execution of the
entrypoint will still be delayed until said control is
next scheduled.
-preferred
specifies that the target control point is to be
temporarily made the preferred control point while
execution of the entrypoint takes place. This control
argument is incompatible with the "-defer_until_ready"
control argument.
-not_preferred
specifies that the target control point will not be
made the preferred control point during the
entrypoint's execution. (Default)
NOTES
This operation enables an entry point to be executed as if
it were executed by the control point itself.
________________________________________
control_point_manager_call Operation: id
This operation returns the unique ID of the current control
point.
SYNTAX AS AN ACTIVE FUNCTION
[cpmc id]
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
SYNTAX AS A COMMAND
cpmc id
________________________________________
control_point_manager_call Operation: list, ls
This operation lists the status of some or all control
points active in the process.
SYNTAX
cpmc ls {IDs} {-control_args}
ARGUMENTS
IDs are the unique IDs of individual control points whose
status is to be displayed.
CONTROL ARGUMENTS
-all, -a specifies that the status of all active control points
is to be displayed.
-meters specifies that the usage meters of the control points
listed are also to be displayed. A control point's
usage meters includes its CPU usage, segment and page
faults counts, and VTOC I/O counts.
-no_meters
specifies that no usage meters are to be displayed.
(Default)
NOTES
At least one control point ID or the "-all" control argument
must be specified for this operation. Use of both control point
IDs and the "-all" control argument is not permitted.
The information always displayed for a control point is its
unique ID in both long and short forms, its state (e.g., ready,
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
blocked), and its description as supplied in the call to
cpm_$create or the use of this command's create or run
operations.
If the status of more than one control point is requested
and usage meters are also requested via the "-meters" control
argument, this operation will also display the usage meters of
the control point scheduler.
________________________________________
control_point_manager_call Operation: pop_preferred
This operation resets the preferred control point to the one
in force before the last use of the push_preferred operation.
See the push_preferred operation below for more information.
SYNTAX
cpmc pop_preferred FLAG
ARGUMENTS
FLAG is either "true" or "false" and should be the value
returned by the last use of the push_preferred
operation.
________________________________________
control_point_manager_call Operation: preferred
This entrypoint returns the ID of the preferred control
point, if any.
SYNTAX AS AN ACTIVE FUNCTION
[cpmc preferred]
SYNTAX AS A COMMAND
cpmc preferred
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
NOTES
The preferred control point is always given priority for
execution over all other control points whenever it is ready.
The effect of this treatment is to cause the preferred control
point to have control over the user's terminal, if it uses the
terminal, as it will receive all IPC wakeups generated by the
terminal. When control point management is first enabled, the
root control point is made the preferred control point.
________________________________________
control_point_manager_call Operation: probe, pb
This operation invokes the probe debugger in the specified
control point.
SYNTAX
cpmc pb ID
ARGUMENTS
ID is the unique ID of the control point in which probe is
to be run.
NOTES
This operation will make the specified control point the
preferred control point while probe is executing in order to
insure that probe can communicate with the user's terminal.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
control_point_manager_call Operation: program_interrupt, pi
This operation signals the program_interrupt condition on
the stack of the specified control point.
SYNTAX
cpmc pi ID {-control_args}
ARGUMENTS
ID is the unique ID of the control point in which
program_interrupt is to be signalled.
CONTROL ARGUMENTS
-preferred
specifies that the control point will be made the
preferred control point before program_interrupt is
signalled. (Default)
-not_preferred
specifies that the control point will not be made the
preferred control point.
________________________________________
control_point_manager_call Operation: push_preferred
This operation makes the specified control point the
preferred control point on a temporary basis.
SYNTAX AS AN ACTIVE FUNCTION
[cpmc push_preferred ID]
SYNTAX AS A COMMAND
cpmc push_preferred ID
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
ARGUMENTS
ID is the unique ID of the control point which is to be
made the preferred control point.
NOTES
This operation returns "true" if it was able to make the
specified control point the preferred control point. The result
of this operation should be used as input to the pop_preferred
operation described above to restore the previous preferred
control point when the actions requiring the new control point to
be preferred are completed.
The following version 2 exec_com fragment demonstrates the
proper use of the push_preferred and pop_preferred operations.
&set pushed false
&on cleanup &begin
cpmc pop_preferred &(pushed)
&end
&set pushed [cpmc push_preferred &1]
...
cpmc pop_preferred &(pushed)
________________________________________
control_point_manager_call Operation: run
This operation creates a new control point to execute the
supplied command line. The control point is destroyed when the
command line completes.
SYNTAX
cpmc run {-control_args} COMMAND_LINE
ARGUMENTS
COMMAND_LINE
is the command line to be executed. The command line
starts with the first non-control argument supplied to
the run operation. If the command line is to start
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
with a hyphen (-), the "-string" control argument
should be used to signify the start of the command
line.
CONTROL ARGUMENTS
-long, -lg
displays a message giving the ID of the newly created
control point. (Default)
-brief, -bf
does not display the message described above.
-start, -sr
marks the new control point as ready for execution.
Actual execution of the control point will begin when
all higher priority control points in the process are
blocked waiting for an IPC wakeup. (Default)
-no_start, -nsr
does not make the new control point as ready for
execution.
-preferred
makes the new control point the preferred control
point. This control argument is incompatible with the
"-no_start" control argument. (Default)
-not_preferred
does not make the new control point the preferred
control point.
-priority N
sets the scheduling priority of the new control point
to N which must be an integer. A ready control point
whose priority is 1 is always scheduled before any
ready control point whose priority is 2, etc. The
default priority is 1.
-comment STR, -com STR
specifies a description of the new control point which
will be displayed by the list operation The default
description is the command line which it will execute.
-independent
specifies that the new control point will be
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
independent of all other control points in the process.
At present, the independence of a control point only
affects when the storage it has used will be released
after it is destroyed. (Default)
-dependent
specifies that the new control point will be a child of
the current control point.
-cl_intermediary ENTRY
specifies the entrypoint to be used as the command
level intermediary for the new control point. ENTRY is
a virtual entrypoint as accepted by the cv_entry_
subroutine.
-default_cl_intermediary
specifies that the new control point is to used the
standard command level intermediary provided by the
control point manager. (Default)
-separate_io_switches {STR}, -sepios {STR}
specifies that the new control point is to have its own
set of standard I/O switches (i.e., user_i/o,
user_input, user_output, and error_output). If STR is
supplied, it is the attach description for the new
control point's user_i/o switch. If STR is not
supplied, its user_i/o will be attached via the syn_
I/O module to the current control point's user_i/o. In
either case, the actual attachment of the I/O switches
will be performed in the new control point before its
initial procedure is invoked.
-shared_io_switches, -shios
specifies that the new control point is to use the same
set of standard I/O switches as the current control
point (Default)
-string COMMAND_LINE, -str COMMAND_LINE
specifies that the command line to be executed starts
with the next argument to the run operation.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
control_point_manager_call Operation: scheduler
This operation blocks the current control point and invokes
the scheduler to run the appropriate ready control point.
SYNTAX
cpmc scheduler
NOTES
It is not usually necessary to use this operation to
schedule control points, because ipc_ calls the control point
scheduler when a wakeup is sent to a control point.
________________________________________
control_point_manager_call Operation: select, sl
This operation marks the specified control point as ready
for execution and makes it the preferred control point.
SYNTAX
cpmc sl ID
ARGUMENTS
ID is the unique ID of the control point to be selected.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
control_point_manager_call Operation: set_cl_intermediary
This operation sets the command level intermediary for the
specified control point.
SYNTAX
cpmc set_cl_intermediary ID {ENTRY} {-control_args}
ARGUMENTS
ID is the unique ID of the control point whose command
level intermediary is to be set.
ENTRY is the new command level intermediary for the
entrypoint. ENTRY is a virtual entrypoint as accepted
by the cv_entry_ subroutine.
CONTROL ARGUMENTS
-default, -dft
specifies that the command level intermediary for the
control point is to be restored to the default supplied
by the control point manager.
NOTES
Either an entrypoint must be supplied or the "-default"
control argument must be used. Both an entrypoint and "-default"
may not be used in a single invocation of this command.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
control_point_manager_call Operation: set_preferred
This entrypoint makes the specified control point the
preferred control.
SYNTAX
cpmc set_preferred ID
ARGUMENTS
ID is the unique ID of the control point which will become
the preferred control point.
________________________________________
control_point_manager_call Operation: start, sr
This entrypoint marks the specified control point as ready
for execution.
SYNTAX
cpmc sr ID
ARGUMENTS
ID is the unique ID of the control point which is to be
marked ready.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
__________________________ __________________________
control_point_manager_call control_point_manager_call
__________________________ __________________________
control_point_manager_call Operation: stop
This entrypoint marks the specified control point as not
ready for execution. The control point will not run until it is
again made ready by this command's select or start operations or
by a call to the cpm_$start entrypoint.
SYNTAX
cpmc stop ID
ARGUMENTS
ID is the unique ID of the control point which is to be
stopped.
________________________________________
control_point_manager_call Operation: wakeup
This operation sends a generic wakeup to the specified
control point.
SYNTAX
cpmc wakeup ID
ARGUMENTS
ID is the unique ID of the control point which is to be
awakened.
NOTES
It is not usually necessary to use this operation to wakeup
blocked control points, because ipc_ calls the control point
scheduler when a wakeup is sent to a control point.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
APPENDIX D
SUBROUTINES
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
Name: cpm_
This subroutine is the main programmer's interface to the
control point management facility.
________________________________________
Entry: cpm_$block
This entrypoint places the current control point in the
blocked state.
USAGE
dcl cpm_$block entry ();
call cpm_$block ();
NOTES
Once a control point is in the blocked state, it will not
become eligible for execution until a subsequent call to
cpm_$wakeup or cpm_$generate_call. Therefore, this entrypoint
should be used with caution. The primary caller of this
entrypoint is intended to be ipc_.
________________________________________
Entry: cpm_$create
This entrypoint creates a new control point.
USAGE
dcl cpm_$create entry (pointer, bit (36) aligned,
fixed binary (35));
call cpm_$create (ccpi_ptr, control_point_id, code);
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
ARGUMENTS
ccpi_ptr (Input)
is a pointer to the create_control_point_info structure
which describes the control point to be created. This
structure is declared in the cpm_create_ctrl_pt_info
include file as follows:
dcl 1 create_control_point_info
aligned based (ccpi_ptr),
2 header,
3 version character (8) unaligned,
3 comment character (64) unaligned,
3 initproc,
4 entry entry (pointer) variable,
4 info_ptr
pointer,
3 user_cl_intermediary
entry (bit (1) aligned)
variable,
3 priority fixed binary,
3 flags,
4 independent
bit (1) unaligned,
4 separate_standard_iocbs
bit (1) unaligned,
4 user_io_attach_desc_given
bit (1) unaligned,
4 user_cl_intermediary_given
bit (1) unaligned,
4 pad bit (32) unaligned,
3 pad bit (36) aligned,
3 user_io_attach_desc_length
fixed binary (21),
2 user_io_attach_desc
character
(ccpi_user_io_attach_desc_length
refer
(create_control_point_info .
user_io_attach_desc_length))
unaligned;
where:
version is the current version of this structure.
The version of this structure described here
is given by the value of the named constant
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
CREATE_CONTROL_POINT_INFO_VERSION_1 which is
defined in the cpm_create_ctrl_pt_info
include file.
comment is the description of the new control point
which will be displayed by the list operation
of the control_point_manager_call command.
initproc.entry
is the initial procedure of the new control
point.
initproc.info_ptr
is the pointer which will be passed as the
argument to the above initial procedure.
user_cl_intermediary
is the command level intermediary for the new
control point if
flags.user_cl_intermediary_given is "1"b;
otherwise, this element of the structure is
ignored.
priority is the scheduling priority for the new
control. A ready control point whose
priority is 1 is always scheduled before any
ready control point whose priority is 2, etc.
flags.independent
if "1"b, the new control point will be
independent of all other control points in
the process; if "0"b, the new control point
will be a child of the current control point.
At present, the independence of a control
point only controls when its storage will be
released after it is destroyed.
flags.separate_standard_iocbs
if "1"b, the new control point will be given
its own set of standard I/O switches (i.e.,
user_i/o, user_input, user_output, and
error_output); if "0"b, the new control point
will share the standard switches of the root
control point if it is independent or the
current control point if it is dependent.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
flags.user_io_attach_desc_given
is only valid when
flags.separate_standard_iocbs is to "1"b. If
"1"b, an attach description for the new
control point's user_i/o switch is supplied
in the user_io_attach_desc element of this
structure; if "0"b, the new control point's
user_i/o switch will be attached via the syn_
I/O module to its parent's user_i/o switch.
flags.user_cl_intermediary_given
if "1"b, the user_cl_intermediary element
above contains the command level intermediary
for the new control point; if "0"b, the new
control point will use the standard command
level intermediary supplied by the control
point manager.
user_io_attach_desc_length
is the length of the user_io_attach_desc
element of this structure.
user_io_attach_desc
is the attach description for the new control
point's user_i/o switch if
flags.user_io_attach_desc_given is "1"b;
otherwise, this element of the structure is
ignored.
control_point_id (Output)
is set to the unique ID of the newly created control
point.
code (Output)
is a standard system status code. Amongst the possible
returned codes, the following codes have special
significance to this entry:
error_table_$unimplemented_version
The version of the create_control_point_info
structure supplied by the caller is not
supported by this entrypoint.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
NOTES
The control is created in the stopped state. It will not be
scheduled for execution until after a call to cpm_$start.
If the new control point is to have separate standard I/O
switches, they are created and attached in the new control point
before the initial procedure is invoked.
________________________________________
Entry: cpm_$destroy
This entrypoint destroys the specified control point.
USAGE
dcl cpm_$destroy entry (bit (36) aligned,
fixed binary (35));
call cpm_$destroy (control_point_id, code);
ARGUMENTS
control_point_id (Input)
is the unique ID of the control point to be destroyed.
code (Output)
is a standard system status code. Amongst the possible
returned codes, the following codes have special
significance to this entry:
cpm_et_$cant_destroy_root
The ID supplied above is that of the root
control point which can never be destroyed.
cpm_et_$control_point_not_found
The ID supplied above does not identify an
active control point.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
NOTES
When a control point is destroyed, the cleanup handlers of
all entrypoints still active in the control point are run, the
control point's standard I/O switches are detached, and the
storage used by its stack is released.
________________________________________
Entry: cpm_$generate_call
This entrypoint runs the specified entrypoint immediately in
the requested control point.
USAGE
dcl cpm_$generate_call entry (bit (36) aligned,
entry (pointer), pointer, fixed binary (35));
call cpm_$generate_call (control_point_id, userproc,
userproc_info_ptr, code);
ARGUMENTS
control_point_id (Input)
is the unique ID of the control point in which the
entrypoint is to be run.
userproc (Input)
is the entrypoint to be run.
userproc_info_ptr (Input)
is a pointer which is supplied as the argument to the
above entrypoint.
code (Output)
is a standard system status code. Amongst the possible
returned codes, the following codes have special
significance to this entry:
cpm_et_$control_point_not_found
The ID supplied above does not identify an
active control point.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
Entry: cpm_$generate_call_preferred
This entrypoint runs the specified entrypoint immediately in
the requested control point. In addition, this entrypoint makes
the specified control point the preferred control point while the
requested entrypoint is being executed.
USAGE
dcl cpm_$generate_call_preferred entry (bit (36) aligned,
entry (pointer), pointer, fixed binary (35));
call cpm_$generate_call_preferred (control_point_id,
userproc, userproc_info_ptr, code);
ARGUMENTS
control_point_id (Input)
is the unique ID of the control point in which the
entrypoint is to be run.
userproc (Input)
is the entrypoint to be run.
userproc_info_ptr (Input)
is a pointer which is passed as the argument to the
above entrypoint.
code (Output)
is a standard system status code. Amongst the possible
returned codes, the following codes have special
significance to this entry:
cpm_et_$control_point_not_found
The ID supplied above does not identify an
active control point.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
Entry: cpm_$generate_call_when_ready
This entrypoint queues a call to the specified entrypoint in
the requested control point which will be executed when the
scheduler next runs said control point.
USAGE
dcl cpm_$generate_call_when_ready entry (bit (36) aligned,
entry (pointer), pointer, fixed binary (35));
call cpm_$generate_call_when_ready (control_point_id,
userproc, userproc_info_ptr, code);
ARGUMENTS
control_point_id (Input)
is the unique ID of the control point in which the
entrypoint is to be run.
userproc (Input)
is the entrypoint to be run.
userproc_info_ptr (Input)
is a pointer which is passed as the argument to the
above entrypoint.
code (Output)
is a standard system status code. Amongst the possible
returned codes, the following codes have special
significance to this entry:
cpm_et_$control_point_not_found
The ID supplied above does not identify an
active control point.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
Entry: cpm_$get_control_point_meters
This entrypoint returns the usage meters for the specified
entrypoint.
USAGE
dcl cpm_$get_control_point_meters entry (bit (36) aligned,
pointer, fixed binary (35));
call cpm_$get_control_point_meters (control_point_id,
cpma_ptr, code);
ARGUMENTS
control_point_id (Input)
is the unique ID of the control point whose meters are
to be returned.
cpma_ptr (Input)
is a pointer to the control_point_meters_argument
structure into which this entrypoint will place the
usage meters. The control_point_meters_argument
structure is declared in the cpm_ctrl_pt_meters include
file as follows.
dcl 1 control_point_meters_argument
aligned based (cpma_ptr),
2 version character (8) unaligned,
2 meters,
3 n_schedules
fixed binary,
3 pad fixed binary,
3 real_time fixed binary (71),
3 usage like process_usage;
where:
version (Input)
is the current version of this structure.
The version of this structure described here
is given by the value of the named constant
CONTROL_POINT_METERS_ARGUMENT_VERSION_1 which
is declared in the cpm_ctrl_pt_meters include
file.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
meters.n_schedules (Output)
is set to the number of times that the
requested control point has actually been run
by the control point scheduler.
meters.real_time (Output)
is set to the number of microseconds of wall
clock time that this control point has been
running.
meters.usage (Output)
is set to the actual usage meters for this
control point. See the writeup of the
hcs_$get_process_usage entrypoint for a
detailed explanation of the elements of this
structure.
code (Output)
is a standard system status code. Amongst the possible
returned codes, the following codes have special
significance to this entry:
cpm_et_$control_point_not_found
The ID supplied above does not identify an
active control point.
error_table_$unimplemented_version
The version of the
control_point_meters_argument requested by
the caller is not supported by this
entrypoint.
________________________________________
Entry: cpm_$get_preferred_control_point
This entrypoint returns the unique ID of the preferred
control point.
USAGE
dcl cpm_$get_preferred_control_point entry ()
returns (bit (36) aligned);
control_point_id = cpm_$get_preferred_control_point ();
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
ARGUMENTS
control_point_id (Output)
is set to the unique ID of the preferred control point
or to "0"b if there is presently no preferred control
point in the process.
NOTES
The preferred control point is always given priority for
execution over all other control points whenever it is ready.
The effect of this treatment is to cause the preferred control
point to have control over the user's terminal, if it uses the
terminal, as it will receive all IPC wakeups generated by the
terminal. When control point management is first enabled, the
root control point is made the preferred control point.
________________________________________
Entry: cpm_$get_scheduler_meters
This entrypoint returns the usage meters of the control
point scheduler.
USAGE
dcl cpm_$get_scheduler_meters entry (pointer,
fixed binary (35));
call cpm_$get_scheduler_meters (cpma_ptr, code);
ARGUMENTS
cpma_ptr (Input)
is a pointer to the control_point_meters_argument
structure into which this entrypoint will place the
usage meters. The control_point_meters_argument
structure is declared in the cpm_ctrl_pt_meters include
file as follows.
dcl 1 control_point_meters_argument
aligned based (cpma_ptr),
2 version character (8) unaligned,
2 meters,
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
3 n_schedules
fixed binary,
3 pad fixed binary,
3 real_time fixed binary (71),
3 usage like process_usage;
where:
version (Input)
is the current version of this structure.
The version of this structure described here
is given by the value of the named constant
CONTROL_POINT_METERS_ARGUMENT_VERSION_1 which
is declared in the cpm_ctrl_pt_meters include
file.
meters.n_schedules (Output)
is set to the number of times that the
scheduler has been invoked.
meters.real_time (Output)
is set to the number of microseconds of wall
clock time that the scheduler has been in
control of the process. This time includes
the time spent blocked waiting for IPC
wakeups from devices or other processes.
meters.usage (Output)
is set to the actual usage meters for the
scheduler. See the writeup of the
hcs_$get_process_usage entrypoint for a
detailed explanation of the elements of this
structure.
code (Output)
is a standard system status code. Amongst the possible
returned codes, the following codes have special
significance to this entry:
error_table_$unimplemented_version
The version of the
control_point_meters_argument requested by
the caller is not supported by this
entrypoint.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
Entry: cpm_$get_user_cl_intermediary
This entrypoint returns the command level intermediary in
use by the specified control point.
USAGE
dcl cpm_$get_user_cl_intermediary entry (bit (36) aligned,
entry (bit (1) aligned), fixed binary (35));
call cpm_$get_user_cl_intermediary (control_point_id,
user_cl_intermediary, code);
ARGUMENTS
control_point_id (Input)
is the unique ID of the control point whose
intermediary is desired.
user_cl_intermediary
(Output)
is set to the entrypoint which is the command level
intermediary for the specified control point.
code (Output)
is a standard system status code. Amongst the possible
returned codes, the following codes have special
significance to this entry:
cpm_et_$control_point_not_found
The ID supplied above does not identify an
active control point.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
Entry: cpm_$pop_preferred_control_point
This entrypoint restores the preferred control point to the
one in force before the last call to
cpm_$push_preferred_control_point.
USAGE
dcl cpm_$pop_preferred_control_point entry
(bit (1) aligned);
call cpm_$pop_preferred_control_point
(pushed_preferred_control_point);
ARGUMENTS
pushed_preferred_control_point
(Input/Output)
is the value returned by the last call to
cpm_$push_preferred_control_point. This entrypoint
will always set this argument to "0"b before returning
to its caller.
________________________________________
Entry: cpm_$push_preferred_control_point
This entrypoint makes the specified control point the
preferred control point if possible while saving the identity of
the prior preferred control point in a stack for later
restoration by the cpm_$pop_preferred_control_point entrypoint.
USAGE
dcl cpm_$push_preferred_control_point entry
(bit (36) aligned, bit (1) aligned,
fixed binary (35));
call cpm_$push_preferred_control_point (control_point_id,
pushed_preferred_control_point, code);
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
ARGUMENTS
control_point_id (Input)
is the unique ID of the control point which is to be
made the preferred control point.
pushed_preferred_control_point
(Output)
is set to "1"b if the requested control point is
successfully made the preferred control point;
otherwise, this argument is set to "0"b.
code (Output)
is a standard system status code. Amongst the possible
returned codes, the following codes have special
significance to this entry:
cpm_et_$control_point_not_found
The ID supplied above does not identify an
active control point.
cpm_et_$preferred_cant_be_stopped
The ID supplied above identifies a control
point in the stopped state. A control point
in the stopped state may not be made the
preferred control point.
cpm_et_$preferred_stack_overflow
The stack of preferred control points if
full.
NOTES
The setting of pushed_preferred_control_point is made
indivisibly with making the specified control point the preferred
control point.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
Entry: cpm_$scheduler
This entrypoint invokes the control point scheduler to run
an appropriate ready control point.
USAGE
dcl cpm_$scheduler entry ();
call cpm_$scheduler ();
NOTES
The primary caller of this entrypoint is intended to be ipc_
when another control point is to be scheduled to run.
________________________________________
Entry: cpm_$set_preferred_control_point
This entrypoint makes the specified control point the
preferred control point.
USAGE
dcl cpm_$set_preferred_control_point entry
(bit (36) aligned, fixed binary (35));
call cpm_$set_preferred_control_point (control_point_id,
code);
ARGUMENTS
control_point_id (Input)
is the unique ID of the control point which is to be
made the preferred control point.
code (Output)
is a standard system status code. Amongst the possible
returned codes, the following codes have special
significance to this entry:
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
cpm_et_$control_point_not_found
The ID supplied above does not identify an
active control point.
cpm_et_$preferred_cant_be_stopped
The ID supplied above identifies a control
point in the stopped state. A control point
in the stopped state may not be made the
preferred control point.
________________________________________
Entry: cpm_$set_user_cl_intermediary
This entrypoint sets the command level intermediary for the
specified control point.
USAGE
dcl cpm_$set_user_cl_intermediary entry (bit (36) aligned,
entry (bit (1) aligned), fixed binary (35));
call cpm_$set_user_cl_intermediary (control_point_id,
user_cl_intermediary, code);
ARGUMENTS
control_point_id (Input)
is the unique ID of the control point whose command
level imtermediary is to be set.
user_cl_intermediary
(Input)
is the entrypoint which is to be the new intermediary
for the above control point. This entry is declared as
dcl user_cl_intermediary entry (bit (1) aligned); call
user_cl_intermediary (return_from_intermediary);
ARGUMENTS
return_from_intermediary (Input)
is "1"b if cpm_overseer_$cl_intermediary is
to return as if "start" had been typed,
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
without getting a new command level or
stopping the current control point.
code (Output)
is a standard system status code. Amongst the possible
returned codes, the following codes have special
significance to this entry:
cpm_et_$control_point_not_found
The ID supplied above does not identify an
active control point.
NOTES
The cl_intermediary is always set to be
cpm_overseer_$cl_intermediary, which creates a new listener level
if the root control point is running, and otherwise stops the
current control point and calls the cpm_$scheduler. The
user_cl_intermediary, if given, is called by
cpm_overseer_$cl_intermediary.
________________________________________
Entry: cpm_$start
This entrypoint marks a control point as ready for
execution.
USAGE
dcl cpm_$start entry (bit (36) aligned, fixed binary (35));
call cpm_$start (control_point_id, code);
ARGUMENTS
control_point_id (Input)
is the unique ID of the control point to be started.
code (Output)
is a standard system status code. Amongst the possible
returned codes, the following codes have special
significance to this entry:
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
cpm_et_$already_started
The ID supplied above identifies a control
point which is already started. Such a
control point is in either the ready or
blocked state.
cpm_et_$control_point_not_found
The ID supplied above does not identify an
active control point.
________________________________________
Entry: cpm_$stop
This entrypoint places a control point in the stopped state.
Once in the stopped state, the scheduler will not run the control
point until after a subsequent call to cpm_$start.
USAGE
dcl cpm_$stop entry (bit (36) aligned, fixed binary (35));
call cpm_$stop (control_point_id, code);
ARGUMENTS
control_point_id (Input)
is the unique ID of the control point to be stopped.
code (Output)
is a standard system status code. Amongst the possible
returned codes, the following codes have special
significance to this entry:
cpm_et_$already_stopped
The ID supplied above identifies a control
point which is already in the stopped state.
cpm_et_$cant_stop_root
The ID supplied above is that of the root
control point which can never be stopped.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
cpm_et_$control_point_not_found
The ID supplied above does not identify an
active control point.
________________________________________
Entry: cpm_$wakeup
This entrypoint sends a generic wakeup to the specified
control point. The wakeup changes the control point's state from
blocked to ready and informs the scheduler that it is again
eligible for execution.
USAGE
dcl cpm_$wakeup entry (bit (36) aligned,
fixed binary (35));
call cpm_$wakeup (control_point_id, code);
ARGUMENTS
control_point_id (Input)
is the unique ID of the control point to be awakened.
code (Output)
is a standard system status code. Amongst the possible
returned codes, the following codes have special
significance to this entry:
cpm_et_$cant_wakeup_when_stopped
The ID supplied above identifies a control
point in the stopped state. Wakeups can only
be sent to control points which are in the
blocked state.
cpm_et_$control_point_not_found
The ID supplied above does not identify an
active control point.
cpm_et_$wakeup_ignored
The ID supplied above identifies a control
point which is already in the ready state.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
____ ____
cpm_ cpm_
____ ____
NOTES
The primary caller of cpm_$wakeup is intended to be ipc_.
This entry sets the state of the control point to ready and puts
the control point into the control point ready queue.
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
_________ _________
cpm_data_ cpm_data_
_________ _________
Name: cpm_data_
This data segment contains useful information about the
state of control point management in the process.
________________________________________
Entry: cpm_data_$n_control_points
This datum is the number of active control points in the
process.
USAGE
dcl cpm_data_$n_control_points fixed binary external;
MTB-753, Revision 2 Control Point Management MTB-753, Revision 2
_____________________ _____________________
get_control_point_id_ get_control_point_id_
_____________________ _____________________
Name: get_control_point_id_
This subroutine returns the unique ID of the current control
point.
USAGE
dcl get_control_point_id_ entry ()
returns (bit (36) aligned);
control_point_id = get_control_point_id_ ();
ARGUMENTS
control_point_id (Output)
is set to the unique ID of the current control point.