summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3alloc.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-07-23 17:15:00 +0000
committerKarl Berry <karl@freefriends.org>2012-07-23 17:15:00 +0000
commit134349701bddf7cbbacf6030c6b9f9838aff96fa (patch)
treeec1140c46e1c0347a671a6fa3cf8af5a79e95f93 /Master/texmf-dist/source/latex/l3kernel/l3alloc.dtx
parentf7855c12c18bb97b7b9e49ab685ee558d8c0b47b (diff)
l3kernel 3990 (17jul12)
git-svn-id: svn://tug.org/texlive/trunk@27108 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3alloc.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3alloc.dtx132
1 files changed, 70 insertions, 62 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3alloc.dtx b/Master/texmf-dist/source/latex/l3kernel/l3alloc.dtx
index d9e59a686a7..6d8f58c86b0 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3alloc.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3alloc.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-%% File: l3alloc.dtx Copyright (C) 1990-2011 The LaTeX3 Project
+%% File: l3alloc.dtx Copyright (C) 1990-2012 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
@@ -35,8 +35,8 @@
%
%<*driver|package>
\RequirePackage{l3names}
-\GetIdInfo$Id: l3alloc.dtx 3355 2012-02-09 07:18:22Z joseph $
- {L3 Experimental register allocation}
+\GetIdInfo$Id: l3alloc.dtx 3986 2012-07-15 19:23:51Z joseph $
+ {L3 Register allocation}
%</driver|package>
%<*driver>
\documentclass[full]{l3doc}
@@ -67,7 +67,7 @@
%
% \begin{documentation}
%
-% Note that this module is only used for generating an pkg{expl3}-based
+% 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.
%
@@ -83,24 +83,29 @@
% \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 32768, but registers numbered above 255 are
+% \item The other registers (\tn{count}, \tn{dimen}, \tn{skip},
+% \tn{muskip}, \tn{box}, and \tn{toks}) range from 0 to 32767
+% (65535 for \LuaTeX{}), but registers numbered above 255 are
% accessed somewhat less efficiently.
% \item Registers could be allocated both globally and locally; the
-% use of registers could also be globally or locally. Here we
+% 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}
+% \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.
%
-% \begin{function}[updated = 2011-09-05]{\alloc_new:nnnN}
+% \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 = 2011-09-05]{\__alloc_new:nnnN}
% \begin{syntax}
-% \cs{alloc_new:nnnN} \Arg{type} \Arg{min} \Arg{max} \meta{function}
+% \cs{__alloc_new:nnnN} \Arg{type} \Arg{min} \Arg{max} \meta{function}
% \end{syntax}
-% Shorthand for allocating new registers. Defines \cs{<type>_new:N} as
+% 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,
@@ -110,20 +115,18 @@
% numbers which should not be used.
% \end{function}
%
-% \section{Internal functions}
-%
-% \begin{function}[updated = 2011-09-05]{\alloc_setup_type:nnn}
+% \begin{function}[updated = 2011-09-05]{\__alloc_setup_type:nnn}
% \begin{syntax}
-% \cs{alloc_setup_type:nnn} \Arg{type} \Arg{min} \Arg{max}
+% \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{function}{\__alloc_reg:nNN}
% \begin{syntax}
-% \cs{alloc_reg:nNN} \Arg{type} \meta{function} \meta{register}
+% \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
@@ -140,28 +143,33 @@
%<*initex>
% \end{macrocode}
%
-% \begin{macro}{\alloc_new:nnnN}
+% \begin{macrocode}
+%<@@=alloc>
+% \end{macrocode}
+%
+% \begin{macro}[int]{\@@_new:nnnN}
% Shorthand for defining new register types and their allocators:
% \begin{macrocode}
-\cs_new_protected:Npn \alloc_new:nnnN #1#2#3#4
+\cs_new_protected:Npn \@@_new:nnnN #1#2#3#4
{
- \alloc_setup_type:nnn {#1} {#2} {#3}
- \cs_new:cpn { #1 _new:N } ##1 { \alloc_reg:nNN {#1} #4 ##1 }
+ \@@_setup_type:nnn {#1} {#2} {#3}
+ \cs_new:cpn { #1 _new:N } ##1 { \@@_reg:nNN {#1} #4 ##1 }
}
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[int]{\alloc_setup_type:nnn}
+% \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. We also need a sequence to store the \enquote{exceptions}.
+% All of those variables are internal to the module |#1|.
% \begin{macrocode}
-\cs_new_protected:Npn \alloc_setup_type:nnn #1#2#3
+\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} }
- \seq_new:c { g_ #1 _allocation_seq }
+ \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} }
+ \seq_new:c { g__ #1 _allocation_seq }
}
% \end{macrocode}
% \end{macro}
@@ -176,44 +184,44 @@
% \end{macro}
%
% \begin{macro}
-% {box_new:N, \dim_new:N, \int_new:N, \muskip_new:N \skip_new:N}
+% {\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}
\luatex_if_engine:TF
- { \alloc_new:nnnN { box } \c_zero \c_max_register_int \tex_chardef:D }
- { \alloc_new:nnnN { box } \c_zero \c_max_register_int \tex_mathchardef:D }
-\alloc_new:nnnN { dim } \c_zero \c_max_register_int \tex_dimendef:D
-\alloc_new:nnnN { int } { 11 } \c_max_register_int \tex_countdef:D
-\alloc_new:nnnN { muskip } \c_zero \c_max_register_int \tex_muskipdef:D
-\alloc_new:nnnN { skip } \c_zero \c_max_register_int \tex_skipdef:D
+ { \@@_new:nnnN { box } \c_zero \c_max_register_int \tex_chardef:D }
+ { \@@_new:nnnN { box } \c_zero \c_max_register_int \tex_mathchardef:D }
+\@@_new:nnnN { dim } \c_zero \c_max_register_int \tex_dimendef:D
+\@@_new:nnnN { int } { 11 } \c_max_register_int \tex_countdef:D
+\@@_new:nnnN { muskip } \c_zero \c_max_register_int \tex_muskipdef:D
+\@@_new:nnnN { skip } \c_zero \c_max_register_int \tex_skipdef:D
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\insert_new:N}
-% \begin{macro}[aux]{\alloc_reserve_insert:n}
+% \begin{macro}[aux]{\@@_reserve_insert:n}
% For inserts, there is a need to reserve space in various other registers.
% \begin{macrocode}
-\alloc_new:nnnN { insert } { 221 } { 254 } \tex_chardef:D
+\@@_new:nnnN { insert } { 221 } { 254 } \tex_chardef:D
\group_begin:
- \cs_set_protected:Npn \alloc_reserve_insert:n #1
+ \cs_set_protected:Npn \@@_reserve_insert:n #1
{
- \tex_ifnum:D #1 > \c_insert_allocation_max_tl \scan_stop:
+ \tex_ifnum:D #1 > \c__insert_allocation_max_tl \scan_stop:
\exp_after:wN \use_none:n
\tex_else:D
\exp_after:wN \use:n
\tex_fi:D
{
- \seq_put_right:Nn \g_box_allocation_seq {#1}
- \seq_put_right:Nn \g_dim_allocation_seq {#1}
- \seq_put_right:Nn \g_int_allocation_seq {#1}
- \seq_put_right:Nn \g_skip_allocation_seq {#1}
- \exp_args:Nf \alloc_reserve_insert:n
+ \seq_put_right:Nn \g__box_allocation_seq {#1}
+ \seq_put_right:Nn \g__dim_allocation_seq {#1}
+ \seq_put_right:Nn \g__int_allocation_seq {#1}
+ \seq_put_right:Nn \g__skip_allocation_seq {#1}
+ \exp_args:Nf \@@_reserve_insert:n
{ \etex_numexpr:D #1 + 1 \scan_stop: }
}
}
- \alloc_reserve_insert:n { 221 }
+ \@@_reserve_insert:n { 221 }
\group_end:
% \end{macrocode}
% \end{macro}
@@ -222,45 +230,45 @@
% Box $255$ is reserved by \TeX{} for output, so is protected here from
% use by the allocator.
% \begin{macrocode}
-\seq_put_right:Nn \g_box_allocation_seq { 255 }
+\seq_put_right:Nn \g__box_allocation_seq { 255 }
% \end{macrocode}
%
-% \begin{macro}[int]{\alloc_reg:nNN}
+% \begin{macro}[int]{\@@_reg:nNN}
% This internal macro performs the actual allocation.
% \begin{macrocode}
-\cs_new_protected:Npn \alloc_reg:nNN #1#2#3
+\cs_new_protected:Npn \@@_reg:nNN #1#2#3
{
- \chk_if_free_cs:N #3
- \tex_global:D #2 #3 \tl_use:c { g_ #1 _allocation_tl } \scan_stop:
+ \__chk_if_free_cs:N #3
+ \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 }
+ \tl_use:c { g__ #1 _allocation_tl }
}
- \alloc_next:n {#1}
+ \@@_next:n {#1}
}
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[aux]{\alloc_next:n}
+% \begin{macro}[aux]{\@@_next:n}
% Finding the next register to use is a question of doing an increment
% then a check: if we run out of registers then it is a fatal error, so
% there is no need to unwind the change. (The check could be done
% first but that needs an additional calculation.) There is a built-in
% loop to handle reserved allocation positions.
% \begin{macrocode}
-\cs_new_protected:Npn \alloc_next:n #1
+\cs_new_protected:Npn \@@_next:n #1
{
- \tl_gset:cx { g_ #1 _allocation_tl }
- { \int_eval:n { \tl_use:c { g_ #1 _allocation_tl } + 1 } }
+ \tl_gset:cx { g__ #1 _allocation_tl }
+ { \int_eval:n { \tl_use:c { g__ #1 _allocation_tl } + 1 } }
\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} }
+ { \tl_use:c { g__ #1 _allocation_tl } }
+ > { \tl_use:c { c__ #1 _allocation_max_tl } }
+ { \__msg_kernel_fatal:nnx { kernel } { out-of-registers } {#1} }
{
- \seq_if_in:cxT { g_ #1 _allocation_seq }
- { \tl_use:c { g_ #1 _allocation_tl } }
- { \alloc_next:n {#1} }
+ \seq_if_in:cxT { g__ #1 _allocation_seq }
+ { \tl_use:c { g__ #1 _allocation_tl } }
+ { \@@_next:n {#1} }
}
}
% \end{macrocode}