summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3alloc.dtx
blob: 8d783bd018f19ff1b13ce2e0bfcd452c20696517 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
% \iffalse meta-comment
%
%% File: l3alloc.dtx Copyright (C) 1990-2012,2014-2016 The LaTeX3 Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version.  The latest version
% of this license is in the file
%
%    http://www.latex-project.org/lppl.txt
%
% This file is part of the "l3kernel bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https://github.com/latex3/latex3
%
% for those people who are interested.
%
%<*driver>
\documentclass[full]{l3doc}
\GetIdInfo$Id: l3alloc.dtx 6805 2016-12-28 22:15:52Z joseph $
  {L3 Register allocation}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \pkg{l3alloc} package\\ Register allocation^^A
%   \thanks{This file describes v\ExplFileVersion,
%      last revised \ExplFileDate.}^^A
% }
%
% \author{^^A
%  The \LaTeX3 Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Released \ExplFileDate}
%
% \maketitle
%
% \begin{documentation}
%
%  Note that this module is only used for generating an \pkg{expl3}-based
%  format. Under \LaTeX{}, the \pkg{etex} package is used for allocation
%  management.
%
%  This module provides the basic mechanism for allocating \TeX{}'s
%  registers. While designing this we have to take into account the
%  following characteristics:
%  \begin{itemize}
%    \item |\box255| is reserved for use in the output routine, so it
%      should not be allocated otherwise.
%    \item \TeX{} can load up $256$ hyphenation patterns (registers
%      \tn{language} $0$ to $255$),
%    \item \TeX{} can load no more than $16$ math families,
%    \item \TeX{} supports no more than $16$ I/O streams for reading
%      (\tn{read}) and $16$ I/O streams for writing (\tn{write}),
%    \item \TeX{} supports no more than $256$ inserts.
%    \item The other registers (\tn{count}, \tn{dimen}, \tn{skip},
%      \tn{muskip}, \tn{box}, and \tn{toks}) range from $0$ to $32\,767$
%      ($65\,535$ for \LuaTeX{}), but registers numbered above $255$ are
%      accessed somewhat less efficiently (except in \LuaTeX{}, where access
%      is \enquote[flat}).
%    \item Registers could be allocated both globally and locally; the
%      use of registers could also be global or local. Here we
%      provide support for globally allocated registers for both
%      global and local use.
%  \end{itemize}
%  We also need to allow for some bookkeeping: we need to know which
%  register was allocated last and which registers can not be
%  allocated by the standard mechanisms.
%
% \section{Internal functions}
%
% Register-based allocation is a low-level process, and is therefore
% only to be used as part of kernel code.
%
% \begin{function}[updated = 2012-11-09]{\__alloc_new:nnnN}
%   \begin{syntax}
%     \cs{__alloc_new:nnnN} \Arg{type} \Arg{min} \Arg{max} \meta{function}
%   \end{syntax}
%   Shorthand for allocating new registers. Defines \cs{\meta{type}_new:N} as
%   and allocator function of the specified \meta{type}, indexed up from
%   \meta{min} to a \meta{max}, and with assignment carried out by
%   the \meta{function}. This process will create two token lists,
%   \cs{g_\meta{type}_allocation_tl} and \cs{c_\meta{type}_allocation_max_tl},
%   to store the current and maximum allocation numbers, respectively.
% \end{function}
%
%  \begin{function}[updated = 2011-09-05]{\__alloc_setup_type:nnn}
%    \begin{syntax}
%      \cs{__alloc_setup_type:nnn} \Arg{type} \Arg{min} \Arg{max}
%    \end{syntax}
%    Sets up the storage needed for the administration of registers of
%    \Arg{type}, which will start allocating at \meta{min} and will issue
%    an error if there is an attempt to allocate past the \meta{max}.
%  \end{function}
%
%  \begin{function}{\__alloc_reg:nNN}
%    \begin{syntax}
%      \cs{__alloc_reg:nNN} \Arg{type} \meta{function} \meta{register}
%    \end{syntax}
%    Preforms the allocation for a new \meta{register} of \meta{type},
%    using the allocator \meta{function} (which will be either a
%    primitive \tn{\ldots def} or \tn{chardef}).
%  \end{function}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{l3alloc} implementation}
%
%    \begin{macrocode}
%<*initex>
%    \end{macrocode}
%
%    \begin{macrocode}
%<@@=alloc>
%    \end{macrocode}
%
% \begin{macro}[int]{\@@_new:nnnN}
%   Shorthand for defining new register types and their allocators: creates
%   the appropriate variables and the allocator function itself.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_new:nnnN #1#2#3#4
  {
    \@@_setup_type:nnn {#1} {#2} {#3}
    \cs_new_protected:cpn { #1 _new:N } ##1 { \@@_reg:nNN {#1} #4 ##1 }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{\@@_setup_type:nnn}
%   For each type of register we need to \enquote{counters} that hold the
%   last allocated global register, plus a constant for the maximum
%   allocation.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_setup_type:nnn #1#2#3
  {
    \tl_new:c   { g__ #1 _allocation_tl }
    \tl_gset:cx { g__ #1 _allocation_tl } { \int_eval:n {#2} }
    \tl_const:cx { c__ #1 _allocation_max_tl } { \int_eval:n {#3} }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\int_eval:n}
%   For bootstrapping purposes, a definition of \cs{int_eval:n} is needed
%   in terms of primitives. This is replaced in \pkg{l3int} with a clearer
%   one.
%    \begin{macrocode}
\cs_new:Npn \int_eval:n #1 { \tex_number:D \etex_numexpr:D #1 \scan_stop: }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {\box_new:N, \dim_new:N, \int_new:N, \muskip_new:N \skip_new:N}
%   To get everything to work correctly for inserts, some register types
%   need to have their allocators set up \enquote{early}. It therefore
%   makes sense to collect most of them together here.
%    \begin{macrocode}
\cs_if_exist:NTF \luatex_luatexversion:D
  { \@@_new:nnnN { box } { 0 } \c_max_register_int \tex_chardef:D }
  { \@@_new:nnnN { box } { 0 } \c_max_register_int \tex_mathchardef:D }
\@@_new:nnnN { dim }     { 0 } \c_max_register_int \tex_dimendef:D
\@@_new:nnnN { int }    { 10 } \c_max_register_int \tex_countdef:D
\@@_new:nnnN { muskip }  { 0 } \c_max_register_int \tex_muskipdef:D
\@@_new:nnnN { skip }    { 0 } \c_max_register_int \tex_skipdef:D
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\insert_new:N}
%   For inserts, there is a need to reserve space in various other registers.
%   First, the basic allocation is done.
%    \begin{macrocode}
\@@_new:nnnN { insert } { 221 } { 254 } \tex_chardef:D
%    \end{macrocode}
%   Reserve a gap in the \texttt{box}, \texttt{dim}, \texttt{int} and
%   \texttt{skip} lists. (An inline token list mapping would read better here,
%   but this does not work until \texttt{int} allocation is available!) Note
%   that \texttt{box255} is reserved by \TeX{} itself (\LuaTeX{} does make
%   this alterable, but that doesn't really do much for us so we ignore
%   that!)
%    \begin{macrocode}
\tl_const:Nn \c__box_allocation_reserve_begin_tl  { 221 }
\tl_const:Nn \c__box_allocation_reserve_end_tl    { 255 }
\tl_const:Nn \c__dim_allocation_reserve_begin_tl  { 221 }
\tl_const:Nn \c__dim_allocation_reserve_end_tl    { 254 }
\tl_const:Nn \c__int_allocation_reserve_begin_tl  { 221 }
\tl_const:Nn \c__int_allocation_reserve_end_tl    { 254 }
\tl_const:Nn \c__skip_allocation_reserve_begin_tl { 221 }
\tl_const:Nn \c__skip_allocation_reserve_end_tl   { 254 }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{\@@_reg:nNN}
%   This internal macro performs the actual allocation.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_reg:nNN #1#2#3
  {
    \__chk_if_free_cs:N #3
    \int_compare:nNnTF
      { \tl_use:c { g__ #1 _allocation_tl } }
      > { \tl_use:c { c__ #1 _allocation_max_tl } }
      { \__msg_kernel_fatal:nnx { kernel } { out-of-registers } {#1} }
      {
        \tex_global:D #2 #3 \tl_use:c { g__ #1 _allocation_tl } \scan_stop:
        \iow_log:x
          {
            \token_to_str:N #3 ~=~ #1 ~register~
            \tl_use:c { g__ #1 _allocation_tl }
          }
        \@@_next:n {#1}
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[aux]{\@@_next:n}
%   Set up the next allocation by adding one to the current number, and if
%   necessary skipping over a reserved block.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_next:n #1
  {
    \tl_gset:cx { g__ #1 _allocation_tl }
      {
        \int_eval:n
          {
            \tl_if_exist:cTF { c__ #1 _allocation_reserve_begin_tl }
              {
                \int_compare:nNnTF
                  { \tl_use:c { g__ #1 _allocation_tl } + 1 }
                  =
                  { \tl_use:c { c__ #1 _allocation_reserve_begin_tl } }
                  { \tl_use:c { c__ #1 _allocation_reserve_end_tl } }
                  { \tl_use:c { g__ #1 _allocation_tl } }
              }
              { \tl_use:c { g__ #1 _allocation_tl } }
            + 1
          }
      }
  }
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</initex>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex