COMPILATION LISTING OF SEGMENT smart_alloc_
	Compiled by: Multics PL/I Compiler, Release 27d, of October 11, 1982
	Compiled at: Honeywell LISD Phoenix, System M
	Compiled on: 11/15/82  1745.8 mst Mon
	    Options: optimize map

        1 /* ***********************************************************
        2*   *                                                         *
        3*   * Copyright, (C) Honeywell Information Systems Inc., 1982 *
        4*   *                                                         *
        5*   * Copyright (c) 1972 by Massachusetts Institute of        *
        6*   * Technology and Honeywell Information Systems, Inc.      *
        7*   *                                                         *
        8*   *********************************************************** */
        9 
       10 
       11 
       12 	/*  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  * */
       13 	/*									*/
       14 	/* N__a_m_e:  smart_alloc_							*/
       15 	/*									*/
       16 	/*      A procedure which performs allocations within areas in an intelligent fashion.	*/
       17 	/*									*/
       18 	/* E__n_t_r_y:  smart_alloc_$smart_alloc_						*/
       19 	/*									*/
       20 	/*      This procedure uses alloc_ to perform an allocation within an area.  If the	*/
       21 	/* allocation fails because the area is full, the procedure signals the "area" condition,	*/
       22 	/* and passes an information structure for use by the handler.  The structure contains	*/
       23 	/* a pointer to the area which is full when the handler is signalled.  On return,	*/
       24 	/* the allocation in reattempted in the area pointed to by this pointer.  The handler	*/
       25 	/* may have changed the pointer to point to a new area, or it may have created more	*/
       26 	/* room in the original area.  If the allocation fails again, the"area condition is	*/
       27 	/* re-signalled, and the process continues.					*/
       28 	/*									*/
       29 	/* U__s_a_g_e									*/
       30 	/*									*/
       31 	/*      All procedures which use smart_alloc_ must have the following rename option in 	*/
       32 	/* their procedure statement:							*/
       33 	/*									*/
       34 	/*	<label>: procedure [( <parms> )] options (rename ((alloc_, smart_alloc_)));	*/
       35 	/*									*/
       36 	/*									*/
       37 	/* Within such procedures, all allocations within an area will be performed by 		*/
       38 	/* smart_alloc_.  The same applies to allocations made in procedures which are		*/
       39 	/* internal to procedures using the rename option.				*/
       40 	/*									*/
       41 	/*      A condition handler should be provided for the "area" condition.		*/
       42 	/* One possible handler is available in the msa_manager_ program.			*/
       43 	/*									*/
       44 	/*									*/
       45 	/* A__l_g_o_r_i_t_h_m								*/
       46 	/*									*/
       47 	/* smart_alloc_								*/
       48 	/*									*/
       49 	/*   (1)	allocates space within the area pointed to by Parea, using alloc_;		*/
       50 	/*   (2)	establishes an "area" condition handler which receives control if the		*/
       51 	/*	allocation fails.							*/
       52 	/*   (3)	if the allocation was successful, returns with:				*/
       53 	/*		Preturn = 'pointer to the allocated space';			*/
       54 
       55 	/*   (4)	if the allocation failed, then:					*/
       56 	/*	(a)	calls  area_full, passing the size of the space to be		*/
       57 	/*		allocated, Parea - the ptr to the area, and an allocation failure id.	*/
       58 	/*	(b)	reattempts the allocation, using the (possibly-modified) area pointed	*/
       59 	/*		to by Parea for the allocation;				*/
       60 	/*									*/
       61 	/*									*/
       62 	/* E__n_t_r_y:  smart_alloc_$area_full						*/
       63 	/*									*/
       64 	/*      This procedure signals the "area" condition, passing a pointer to an information	*/
       65 	/* structure describing the nature of the condition.  Programs which call lower-ring	*/
       66 	/* subroutines that perform allocations within a caller-supplied area can use this	*/
       67 	/* procedure to recover from allocation failures in these lower-ring subroutines.	*/
       68 	/*									*/
       69 	/* U__s_a_g_e									*/
       70 	/*									*/
       71 	/* 	dcl  smart_alloc_$area_full entry (fixed bin, ptr, bit(70) aligned);		*/
       72 	/*									*/
       73 	/*	call smart_alloc_$area_full (size, area_ptr, id);				*/
       74 	/*									*/
       75 	/* 1) size	is the amount of space required to satisfy the current allocation.	*/
       76 	/*		If "size" = 0, then the amount of space required to satisfy the 	*/
       77 	/*		the allocation requirements is unknown (eg, if if hcs_$status	*/
       78 	/*		returned an  error_table_$noalloc  error code).			*/
       79 	/*		The caller's "area" handler must make this space 			*/
       80 	/*		available if it returns normally after being signalled.		*/
       81 	/* 2) area_ptr	is a pointer to the area in which the allocation failed.  The value	*/
       82 	/*		of this pointer may be changed by the handler of the "area" condition	*/
       83 	/*		raised by smart_alloc_$area_full.  The new value should be used when	*/
       84 	/*		the allocation is reattempted.				*/
       85 	/* 3) id		is "0"b. (Input)						*/
       86 	/*		is an allocation failure id which should be passed to area_full	*/
       87 	/*		if the allocation fails again. (Output)				*/
       88 	/*									*/
       89 	/* A__l_g_o_r_i_t_h_m								*/
       90 	/*									*/
       91 	/* area_full								*/
       92 	/*									*/
       93 	/*   (1)  assigns a unique bit string to "id" if its "0"b.				*/
       94 	/*   (2)	fills in the information structure shown below, using the size and area_ptr	*/
       95 	/*        parameters, and the assigned allocation failure id.			*/
       96 	/*									*/
       97 	/*  dcl 1 info		aligned,						*/
       98 	/*	2 length		fixed bin,	/* length of this structure (in words)	*/
       99 	/*	2 version		fixed bin,	/* version of this structure (1)	*/
      100 	/*	2 action_flags	aligned,						*/
      101 	/*	  3 cant_restart	bit(1) unal,	/* off => allocation can be restarted.	*/
      102 	/*	  3 default_restart bit(1) unal,	/* off => handler must do something.	*/
      103 	/*	2 info_string	char(256) varying,	/* an informative error message.	*/
      104 	/*	2 status_code	fixed bin(35),	/* error_table_$noalloc		*/
      105 	/*	2 Parea		ptr,		/* ptr to area in which alloc. failed	*/
      106 	/*	2 size		fixed bin,	/* amt of space needed for alloc.	*/
      107 	/*	2 id		bit(70) aligned;	/* allocatin failure id.		*/
      108 	/*									*/
      109 	/*   (3)	signals the "area" condition, passing a pointer to the information structure	*/
      110 	/*	shown above as the "info_ptr" of the signalled condition. (See signal_).	*/
      111 	/*   (4)	returns to its caller.						*/
      112 
      113 	/* N__o_t_e_s									*/
      114 	/*									*/
      115 	/* The caller's "area" handler may:						*/
      116 	/*   (1)	execute a non-local go to instruction to terminate the allocation.		*/
      117 	/*   (2)	free at least "size" amount of space in the area pointed to by "area_ptr", so	*/
      118 	/*	that the allocation can be completed, unless "size" is zero, in which case an	*/
      119 	/*	arbitrary amount of space could be freed.  If there were still too little space	*/
      120 	/*	to satisfy the allocation requirements, then the "area" handler could identify	*/
      121 	/*	this condition by observing that "id" is still the same, and could take other	*/
      122 	/*	action, including freeing more space and trying again.			*/
      123 	/*   (3)	change the value of the area pointer which was used in the allocation to point	*/
      124 	/*	to another area in which the allocation would be attempted.  The programmer	*/
      125 	/*	must take care that no dummy arguments are created when this area pointer	*/
      126 	/*	is passed as an argument to another subroutine which will be performing 	*/
      127 	/*	allocations within the area.  If a dummy argument were created, then		*/
      128 	/*	the "area" condition handler could not change the value of the area pointer in	*/
      129 	/*	any subroutine using this dummy pointer.				*/
      130 	/*									*/
      131 	/* E__x_a_m_p_l_e								*/
      132 	/*									*/
      133 	/*      id = "0"b;								*/
      134 	/* call_again:								*/
      135 	/*      call hcs_$status (dir, ent, chase, addr(status_block), area_ptr, code);		*/
      136 	/*      if code = error_table_$noalloc then do;					*/
      137 	/*           call smart_alloc_$area_full (0, area_ptr, id);				*/
      138 	/*	   go to call_again;						*/
      139 	/*	   end;								*/
      140 	/*									*/
      141 	/*									*/
      142 	/* S__t_a_t_u_s									*/
      143 	/*									*/
      144 	/* 1) Created:  Jul, 1972 by G. C. Dixon					*/
      145 	/* 2) Modified: Apr, 1973 by G. C. Dixon; use "id" instead of a fixed bin(35) number.	*/
      146 	/* 3) Modified: Jul, 1973 by G. C. Dixon; include standard condition info header in info	*/
      147 	/*				  structure				*/
      148 	/*									*/
      149 	/*  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  * */
      150 
      151 
      152 /**/
      153 /*  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  */
      154 
      155 
      156 smart_alloc_:	procedure (Asize, Parea, Preturn);
      157 
      158 
      159 
      160      dcl						/* 	parameters			*/
      161 
      162 	Asize			fixed binary, 	/* size of the space to be allocated. (Input) 	*/
      163 	Parea			ptr,		/* pointer to the allocation area. (Input) 	*/
      164 	Preturn			ptr,		/* pointer to the allocated space. (Output) 	*/
      165 
      166 	id			bit(70) aligned;	/* unique id of this allocation failure.	*/
      167 
      168 
      169      dcl						/*	automatic variables			*/
      170 	1 info,
      171 	  2 length		fixed bin,	/* length of this structure (in words)		*/
      172 	  2 version		fixed bin,	/* version of this structure (1).		*/
      173 	  2 action_flags		aligned,
      174 	    3 cant_restart		bit(1) unal,	/* off => allocation can be retried.		*/
      175 	    3 default_restart	bit(1) unal,	/* off => allocation will fail again if no action	*/
      176 						/*        is taken except to return.		*/
      177 	    3 pad			bit(34) unal,
      178 	  2 info_string		char(256) var,	/* an information string.			*/
      179 	  2 status_code		fixed bin(35),	/* a status code.				*/
      180 	  2 Parea			ptr,		/* ptr to area in which allocation failed.	*/
      181 	  2 size			fixed bin,	/* amt of space needed for the allocation.	*/
      182 	  2 id			bit(70) aligned,	/* allocation failure id.			*/
      183 	failure_id		bit(70) aligned;
      184 
      185 
      186      dcl						/*	program entries and builtin functions	*/
      187 	addr			builtin,
      188 	alloc_			entry (fixed binary, ptr, ptr),
      189 	area			condition,
      190 	null			builtin,
      191 	signal_			entry (char(*), ptr, ptr),
      192 	size			builtin,
      193 	unique_bits_		entry returns (bit(70) aligned);
      194 
      195      dcl						/* 	static variable			*/
      196 	error_table_$noalloc	fixed bin(35) ext static;
      197 
      198 
      199 
      200 
      201 
      202 	failure_id = "0"b;				/* initialize failure id.			*/
      203 						/* user's "area" condition handler is re-signalled*/
      204 allocate: on area					/* trap "area" condition signalled by alloc_.	*/
      205 	     go to handler;
      206 	call alloc_ (Asize, Parea, Preturn);		/* attempt the allocation. 			*/
      207 	return;
      208 
      209 handler:  revert area;				/* revert to the caller's "area" condition	*/
      210 	call area_full (Asize, Parea, failure_id);	/* handler, and call the area_full subroutine.	*/
      211 	go to allocate;				/* then, retry the allocation.		*/
      212 
      213 /*  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  */
      214 
      215 
      216 
      217 area_full:	entry (Asize, Parea, id);
      218 
      219 	if id = "0"b then				/* initialize failure id if it hasn't been done	*/
      220 	     id = unique_bits_();
      221 
      222 	info.size = Asize;				/* fill in the values of the data structure to	*/
      223 	info.Parea = Parea;				/* be passed to the user's "area" handler when	*/
      224 	info.id = id;				/* we signal "area".			*/
      225 
      226 	info.length = size (info);			/* fill in header section of the data structure.	*/
      227 	info.version = 1;
      228 	info.cant_restart,
      229 	info.default_restart = "0"b;
      230 	info.pad = "0"b;				/* zero pad in case new action flags invented.	*/
      231 	info.info_string = "";
      232 	info.status_code = error_table_$noalloc;
      233 
      234 	call signal_ ("area", null, addr (info));	/* signal the "area" condition, and return.	*/
      235 
      236 	Parea = info.Parea;				/* return the updated area ptr for calls from	*/
      237 						/* smart_alloc_ because PL/I creates a dummy ptr	*/
      238 						/* to the area when an allocation is made via	*/
      239 						/* an allocate statement.			*/
      240 
      241 
      242 /*  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  **  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  */
      243 
      244 
      245 	end smart_alloc_;
	SOURCE FILES USED IN THIS COMPILATION.

LINE      NUMBER  DATE MODIFIED     NAME			PATHNAME
             0    11/15/82  1527.9  smart_alloc_.pl1                  >dumps>old>recomp>smart_alloc_.pl1
	NAMES DECLARED IN THIS COMPILATION.

IDENTIFIER	     OFFSET    LOC STORAGE CLASS   DATA TYPE		ATTRIBUTES AND REFERENCES
								(* indicates a set context)

NAMES DECLARED BY DECLARE STATEMENT.
Asize                                  parameter       fixed bin(17,0)          dcl 160 set ref 156 206* 210* 217 222
Parea                                  parameter       pointer                  dcl 160 in procedure "smart_alloc_" set ref 156 206*
                                                                                  210* 217 223 236*
Parea                   106     000100 automatic       pointer                  level 2 in structure "info" dcl 169 in procedure
                                                                                  "smart_alloc_" set ref 223* 236
Preturn                                parameter       pointer                  dcl 160 set ref 156 206*
action_flags              2     000100 automatic       structure                level 2 dcl 169
addr                                                   builtin function         dcl 186 ref 234 234
alloc_                          000010 constant        entry                    external dcl 186 ref 206
area                            000216 stack reference condition                dcl 186 ref 204 209
cant_restart              2     000100 automatic       bit(1)                   level 3 packed unaligned dcl 169 set ref 228*
default_restart           2(01) 000100 automatic       bit(1)                   level 3 packed unaligned dcl 169 set ref 228*
error_table_$noalloc            000016 external static fixed bin(35,0)          dcl 195 ref 232
failure_id                      000214 automatic       bit(70)                  dcl 169 set ref 202* 210*
id                      111     000100 automatic       bit(70)                  level 2 in structure "info" dcl 169 in procedure
                                                                                  "smart_alloc_" set ref 224*
id                                     parameter       bit(70)                  dcl 160 in procedure "smart_alloc_" set ref 217 219
                                                                                  219* 224
info                            000100 automatic       structure                level 1 unaligned dcl 169 set ref 226 234 234
info_string               3     000100 automatic       varying char(256)        level 2 dcl 169 set ref 231*
length                          000100 automatic       fixed bin(17,0)          level 2 dcl 169 set ref 226*
null                                                   builtin function         dcl 186 ref 234 234
pad                       2(02) 000100 automatic       bit(34)                  level 3 packed unaligned dcl 169 set ref 230*
signal_                         000012 constant        entry                    external dcl 186 ref 234
size                                                   builtin function         dcl 186 in procedure "smart_alloc_" ref 226
size                    110     000100 automatic       fixed bin(17,0)          level 2 in structure "info" dcl 169 in procedure
                                                                                  "smart_alloc_" set ref 222*
status_code             104     000100 automatic       fixed bin(35,0)          level 2 dcl 169 set ref 232*
unique_bits_                    000014 constant        entry                    external dcl 186 ref 219
version                   1     000100 automatic       fixed bin(17,0)          level 2 dcl 169 set ref 227*

NAMES DECLARED BY EXPLICIT CONTEXT.
allocate                        000025 constant        label                    dcl 204 ref 211
area_full                       000102 constant        entry                    external dcl 217 ref 210
handler                         000061 constant        label                    dcl 209 ref 204
smart_alloc_                    000016 constant        entry                    external dcl 156

THERE WERE NO NAMES DECLARED BY CONTEXT OR IMPLICATION.

STORAGE REQUIREMENTS FOR THIS PROGRAM.

	Object	Text	Link	Symbol	Defs	Static
Start          0       0       306         326     214         316
Length       500     214        20         135      72           0

BLOCK NAME	         STACK SIZE     TYPE		WHY NONQUICK/WHO SHARES STACK FRAME
smart_alloc_                        176 external procedure  is an external procedure.  
on unit on line 204                  64 on unit               

STORAGE FOR AUTOMATIC VARIABLES.

STACK FRAME                 LOC IDENTIFIER                  BLOCK NAME
smart_alloc_             000100 info                        smart_alloc_
                         000214 failure_id                  smart_alloc_

THE FOLLOWING EXTERNAL OPERATORS ARE USED BY THIS PROGRAM.
call_ext_in         call_ext_out_desc   call_ext_out        return              tra_ext             enable
ext_entry           int_entry

THE FOLLOWING EXTERNAL ENTRIES ARE CALLED BY THIS PROGRAM.
alloc_                        signal_                       unique_bits_

THE FOLLOWING EXTERNAL VARIABLES ARE USED BY THIS PROGRAM.
error_table_$noalloc




   LINE    LOC      LINE    LOC      LINE    LOC      LINE    LOC      LINE    LOC      LINE    LOC      LINE    LOC   
    156 000012       202 000023       204 000025       206 000044       207 000060       209 000061       210 000062
    211 000075       217 000076       219 000107       222 000124       223 000127       224 000132       226 000140
    227 000142       228 000144       230 000150       231 000152       232 000153       234 000156       236 000203
    245 000206


                                          -----------------------------------------------------------


Historical Background

This edition of the Multics software materials and documentation is provided and donated
to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. 
as a contribution to computer science knowledge.  
This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology,
Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL
and BULL HN Information Systems Inc. to the development of this operating system. 
Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970),
renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership
of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture 
for managing computer hardware properly and for executing programs. Many subsequent operating systems 
incorporated Multics principles.
Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., 
as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. .

                                          -----------------------------------------------------------

Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without
fee is hereby granted,provided that the below copyright notice and historical background appear in all copies
and that both the copyright notice and historical background and this permission notice appear in supporting
documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining
to distribution of the programs without specific prior written permission.
    Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc.
    Copyright 2006 by BULL HN Information Systems Inc.
    Copyright 2006 by Bull SAS
    All Rights Reserved