[hcoop/debian/mlton.git] / doc / guide / src / CommonBlock.adoc

CommonBlock
===========

<:CommonBlock:> is an optimization pass for the <:SSA:>
<:IntermediateLanguage:>, invoked from <:SSASimplify:>.

== Description ==

It eliminates equivalent blocks in a <:SSA:> function.  The
equivalence criteria requires blocks to have no arguments or
statements and transfer via `Raise`, `Return`, or `Goto` of a single
global variable.

== Implementation ==

* <!ViewGitFile(mlton,master,mlton/ssa/common-block.fun)>

== Details and Notes ==

* Rewrites
+
----
L_X ()
  raise (global_Y)
----
+
to
+
----
L_X ()
  L_Y' ()
----
+
and adds
+
----
L_Y' ()
  raise (global_Y)
----
+
to the <:SSA:> function.

* Rewrites
+
----
L_X ()
  return (global_Y)
----
+
to
+
----
L_X ()
  L_Y' ()
----
+
and adds
+
----
L_Y' ()
  return (global_Y)
----
+
to the <:SSA:> function.

* Rewrites
+
----
L_X ()
  L_Z (global_Y)
----
+
to
+
----
L_X ()
  L_Y' ()
----
+
and adds
+
----
L_Y' ()
  L_Z (global_Y)
----
+
to the <:SSA:> function.

The <:Shrink:> pass rewrites all uses of `L_X` to `L_Y'` and drops `L_X`.

For example, all uncaught `Overflow` exceptions in a <:SSA:> function
share the same raising block.
Commit	Line	Data
7f918cf1 CE	1	CommonBlock
	2	===========
	3
	4	<:CommonBlock:> is an optimization pass for the <:SSA:>
	5	<:IntermediateLanguage:>, invoked from <:SSASimplify:>.
	6
	7	== Description ==
	8
	9	It eliminates equivalent blocks in a <:SSA:> function. The
	10	equivalence criteria requires blocks to have no arguments or
	11	statements and transfer via `Raise`, `Return`, or `Goto` of a single
	12	global variable.
	13
	14	== Implementation ==
	15
	16	* <!ViewGitFile(mlton,master,mlton/ssa/common-block.fun)>
	17
	18	== Details and Notes ==
	19
	20	* Rewrites
	21	+
	22	----
	23	L_X ()
	24	raise (global_Y)
	25	----
	26	+
	27	to
	28	+
	29	----
	30	L_X ()
	31	L_Y' ()
	32	----
	33	+
	34	and adds
	35	+
	36	----
	37	L_Y' ()
	38	raise (global_Y)
	39	----
	40	+
	41	to the <:SSA:> function.
	42
	43	* Rewrites
	44	+
	45	----
	46	L_X ()
	47	return (global_Y)
	48	----
	49	+
	50	to
	51	+
	52	----
	53	L_X ()
	54	L_Y' ()
	55	----
	56	+
	57	and adds
	58	+
	59	----
	60	L_Y' ()
	61	return (global_Y)
	62	----
	63	+
	64	to the <:SSA:> function.
65
66	* Rewrites
67	+
68	----
69	L_X ()
70	L_Z (global_Y)
71	----
72	+
73	to
74	+
75	----
76	L_X ()
77	L_Y' ()
78	----
79	+
80	and adds
81	+
82	----
83	L_Y' ()
84	L_Z (global_Y)
85	----
86	+
87	to the <:SSA:> function.
88
89	The <:Shrink:> pass rewrites all uses of `L_X` to `L_Y'` and drops `L_X`.
90
91	For example, all uncaught `Overflow` exceptions in a <:SSA:> function
92	share the same raising block.