diff options
Diffstat (limited to 'Doc/lib/libthreading.tex')
| -rw-r--r-- | Doc/lib/libthreading.tex | 728 |
1 files changed, 0 insertions, 728 deletions
diff --git a/Doc/lib/libthreading.tex b/Doc/lib/libthreading.tex deleted file mode 100644 index 19c496e..0000000 --- a/Doc/lib/libthreading.tex +++ /dev/null @@ -1,728 +0,0 @@ -\section{\module{threading} --- - Higher-level threading interface} - -\declaremodule{standard}{threading} -\modulesynopsis{Higher-level threading interface.} - - -This module constructs higher-level threading interfaces on top of the -lower level \refmodule{thread} module. - -The \refmodule[dummythreading]{dummy_threading} module is provided for -situations where \module{threading} cannot be used because -\refmodule{thread} is missing. - -This module defines the following functions and objects: - -\begin{funcdesc}{activeCount}{} -Return the number of \class{Thread} objects currently alive. The -returned count is equal to the length of the list returned by -\function{enumerate()}. -\end{funcdesc} - -\begin{funcdescni}{Condition}{} -A factory function that returns a new condition variable object. -A condition variable allows one or more threads to wait until they -are notified by another thread. -\end{funcdescni} - -\begin{funcdesc}{currentThread}{} -Return the current \class{Thread} object, corresponding to the -caller's thread of control. If the caller's thread of control was not -created through the -\module{threading} module, a dummy thread object with limited functionality -is returned. -\end{funcdesc} - -\begin{funcdesc}{enumerate}{} -Return a list of all \class{Thread} objects currently alive. The list -includes daemonic threads, dummy thread objects created by -\function{currentThread()}, and the main thread. It excludes -terminated threads and threads that have not yet been started. -\end{funcdesc} - -\begin{funcdescni}{Event}{} -A factory function that returns a new event object. An event manages -a flag that can be set to true with the \method{set()} method and -reset to false with the \method{clear()} method. The \method{wait()} -method blocks until the flag is true. -\end{funcdescni} - -\begin{classdesc*}{local}{} -A class that represents thread-local data. Thread-local data are data -whose values are thread specific. To manage thread-local data, just -create an instance of \class{local} (or a subclass) and store -attributes on it: - -\begin{verbatim} -mydata = threading.local() -mydata.x = 1 -\end{verbatim} - -The instance's values will be different for separate threads. - -For more details and extensive examples, see the documentation string -of the \module{_threading_local} module. - -\versionadded{2.4} -\end{classdesc*} - -\begin{funcdesc}{Lock}{} -A factory function that returns a new primitive lock object. Once -a thread has acquired it, subsequent attempts to acquire it block, -until it is released; any thread may release it. -\end{funcdesc} - -\begin{funcdesc}{RLock}{} -A factory function that returns a new reentrant lock object. -A reentrant lock must be released by the thread that acquired it. -Once a thread has acquired a reentrant lock, the same thread may -acquire it again without blocking; the thread must release it once -for each time it has acquired it. -\end{funcdesc} - -\begin{funcdescni}{Semaphore}{\optional{value}} -A factory function that returns a new semaphore object. A -semaphore manages a counter representing the number of \method{release()} -calls minus the number of \method{acquire()} calls, plus an initial value. -The \method{acquire()} method blocks if necessary until it can return -without making the counter negative. If not given, \var{value} defaults to -1. -\end{funcdescni} - -\begin{funcdesc}{BoundedSemaphore}{\optional{value}} -A factory function that returns a new bounded semaphore object. A bounded -semaphore checks to make sure its current value doesn't exceed its initial -value. If it does, \exception{ValueError} is raised. In most situations -semaphores are used to guard resources with limited capacity. If the -semaphore is released too many times it's a sign of a bug. If not given, -\var{value} defaults to 1. -\end{funcdesc} - -\begin{classdesc*}{Thread} -A class that represents a thread of control. This class can be safely -subclassed in a limited fashion. -\end{classdesc*} - -\begin{classdesc*}{Timer} -A thread that executes a function after a specified interval has passed. -\end{classdesc*} - -\begin{funcdesc}{settrace}{func} -Set a trace function\index{trace function} for all threads started -from the \module{threading} module. The \var{func} will be passed to -\function{sys.settrace()} for each thread, before its \method{run()} -method is called. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{setprofile}{func} -Set a profile function\index{profile function} for all threads started -from the \module{threading} module. The \var{func} will be passed to -\function{sys.setprofile()} for each thread, before its \method{run()} -method is called. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{stack_size}{\optional{size}} -Return the thread stack size used when creating new threads. The -optional \var{size} argument specifies the stack size to be used for -subsequently created threads, and must be 0 (use platform or -configured default) or a positive integer value of at least 32,768 (32kB). -If changing the thread stack size is unsupported, a \exception{ThreadError} -is raised. If the specified stack size is invalid, a \exception{ValueError} -is raised and the stack size is unmodified. 32kB is currently the minimum -supported stack size value to guarantee sufficient stack space for the -interpreter itself. Note that some platforms may have particular -restrictions on values for the stack size, such as requiring a minimum -stack size > 32kB or requiring allocation in multiples of the system -memory page size - platform documentation should be referred to for -more information (4kB pages are common; using multiples of 4096 for -the stack size is the suggested approach in the absence of more -specific information). -Availability: Windows, systems with \POSIX{} threads. -\versionadded{2.5} -\end{funcdesc} - -Detailed interfaces for the objects are documented below. - -The design of this module is loosely based on Java's threading model. -However, where Java makes locks and condition variables basic behavior -of every object, they are separate objects in Python. Python's \class{Thread} -class supports a subset of the behavior of Java's Thread class; -currently, there are no priorities, no thread groups, and threads -cannot be destroyed, stopped, suspended, resumed, or interrupted. The -static methods of Java's Thread class, when implemented, are mapped to -module-level functions. - -All of the methods described below are executed atomically. - - -\subsection{Lock Objects \label{lock-objects}} - -A primitive lock is a synchronization primitive that is not owned -by a particular thread when locked. In Python, it is currently -the lowest level synchronization primitive available, implemented -directly by the \refmodule{thread} extension module. - -A primitive lock is in one of two states, ``locked'' or ``unlocked''. -It is created in the unlocked state. It has two basic methods, -\method{acquire()} and \method{release()}. When the state is -unlocked, \method{acquire()} changes the state to locked and returns -immediately. When the state is locked, \method{acquire()} blocks -until a call to \method{release()} in another thread changes it to -unlocked, then the \method{acquire()} call resets it to locked and -returns. The \method{release()} method should only be called in the -locked state; it changes the state to unlocked and returns -immediately. If an attempt is made to release an unlocked lock, a -\exception{RuntimeError} will be raised. - -When more than one thread is blocked in \method{acquire()} waiting for -the state to turn to unlocked, only one thread proceeds when a -\method{release()} call resets the state to unlocked; which one of the -waiting threads proceeds is not defined, and may vary across -implementations. - -All methods are executed atomically. - -\begin{methoddesc}[Lock]{acquire}{\optional{blocking\code{ = 1}}} -Acquire a lock, blocking or non-blocking. - -When invoked without arguments, block until the lock is -unlocked, then set it to locked, and return true. - -When invoked with the \var{blocking} argument set to true, do the -same thing as when called without arguments, and return true. - -When invoked with the \var{blocking} argument set to false, do not -block. If a call without an argument would block, return false -immediately; otherwise, do the same thing as when called -without arguments, and return true. -\end{methoddesc} - -\begin{methoddesc}[Lock]{release}{} -Release a lock. - -When the lock is locked, reset it to unlocked, and return. If -any other threads are blocked waiting for the lock to become -unlocked, allow exactly one of them to proceed. - -Do not call this method when the lock is unlocked. - -There is no return value. -\end{methoddesc} - - -\subsection{RLock Objects \label{rlock-objects}} - -A reentrant lock is a synchronization primitive that may be -acquired multiple times by the same thread. Internally, it uses -the concepts of ``owning thread'' and ``recursion level'' in -addition to the locked/unlocked state used by primitive locks. In -the locked state, some thread owns the lock; in the unlocked -state, no thread owns it. - -To lock the lock, a thread calls its \method{acquire()} method; this -returns once the thread owns the lock. To unlock the lock, a -thread calls its \method{release()} method. -\method{acquire()}/\method{release()} call pairs may be nested; only -the final \method{release()} (the \method{release()} of the outermost -pair) resets the lock to unlocked and allows another thread blocked in -\method{acquire()} to proceed. - -\begin{methoddesc}[RLock]{acquire}{\optional{blocking\code{ = 1}}} -Acquire a lock, blocking or non-blocking. - -When invoked without arguments: if this thread already owns -the lock, increment the recursion level by one, and return -immediately. Otherwise, if another thread owns the lock, -block until the lock is unlocked. Once the lock is unlocked -(not owned by any thread), then grab ownership, set the -recursion level to one, and return. If more than one thread -is blocked waiting until the lock is unlocked, only one at a -time will be able to grab ownership of the lock. There is no -return value in this case. - -When invoked with the \var{blocking} argument set to true, do the -same thing as when called without arguments, and return true. - -When invoked with the \var{blocking} argument set to false, do not -block. If a call without an argument would block, return false -immediately; otherwise, do the same thing as when called -without arguments, and return true. -\end{methoddesc} - -\begin{methoddesc}[RLock]{release}{} -Release a lock, decrementing the recursion level. If after the -decrement it is zero, reset the lock to unlocked (not owned by any -thread), and if any other threads are blocked waiting for the lock to -become unlocked, allow exactly one of them to proceed. If after the -decrement the recursion level is still nonzero, the lock remains -locked and owned by the calling thread. - -Only call this method when the calling thread owns the lock. A -\exception{RuntimeError} is raised if this method is called when the -lock is unlocked. - -There is no return value. -\end{methoddesc} - - -\subsection{Condition Objects \label{condition-objects}} - -A condition variable is always associated with some kind of lock; -this can be passed in or one will be created by default. (Passing -one in is useful when several condition variables must share the -same lock.) - -A condition variable has \method{acquire()} and \method{release()} -methods that call the corresponding methods of the associated lock. -It also has a \method{wait()} method, and \method{notify()} and -\method{notifyAll()} methods. These three must only be called when -the calling thread has acquired the lock, otherwise a -\exception{RuntimeError} is raised. - -The \method{wait()} method releases the lock, and then blocks until it -is awakened by a \method{notify()} or \method{notifyAll()} call for -the same condition variable in another thread. Once awakened, it -re-acquires the lock and returns. It is also possible to specify a -timeout. - -The \method{notify()} method wakes up one of the threads waiting for -the condition variable, if any are waiting. The \method{notifyAll()} -method wakes up all threads waiting for the condition variable. - -Note: the \method{notify()} and \method{notifyAll()} methods don't -release the lock; this means that the thread or threads awakened will -not return from their \method{wait()} call immediately, but only when -the thread that called \method{notify()} or \method{notifyAll()} -finally relinquishes ownership of the lock. - -Tip: the typical programming style using condition variables uses the -lock to synchronize access to some shared state; threads that are -interested in a particular change of state call \method{wait()} -repeatedly until they see the desired state, while threads that modify -the state call \method{notify()} or \method{notifyAll()} when they -change the state in such a way that it could possibly be a desired -state for one of the waiters. For example, the following code is a -generic producer-consumer situation with unlimited buffer capacity: - -\begin{verbatim} -# Consume one item -cv.acquire() -while not an_item_is_available(): - cv.wait() -get_an_available_item() -cv.release() - -# Produce one item -cv.acquire() -make_an_item_available() -cv.notify() -cv.release() -\end{verbatim} - -To choose between \method{notify()} and \method{notifyAll()}, consider -whether one state change can be interesting for only one or several -waiting threads. E.g. in a typical producer-consumer situation, -adding one item to the buffer only needs to wake up one consumer -thread. - -\begin{classdesc}{Condition}{\optional{lock}} -If the \var{lock} argument is given and not \code{None}, it must be a -\class{Lock} or \class{RLock} object, and it is used as the underlying -lock. Otherwise, a new \class{RLock} object is created and used as -the underlying lock. -\end{classdesc} - -\begin{methoddesc}{acquire}{*args} -Acquire the underlying lock. -This method calls the corresponding method on the underlying -lock; the return value is whatever that method returns. -\end{methoddesc} - -\begin{methoddesc}{release}{} -Release the underlying lock. -This method calls the corresponding method on the underlying -lock; there is no return value. -\end{methoddesc} - -\begin{methoddesc}{wait}{\optional{timeout}} -Wait until notified or until a timeout occurs. If the calling thread -has not acquired the lock when this method is called, a -\exception{RuntimeError} is raised. - -This method releases the underlying lock, and then blocks until it is -awakened by a \method{notify()} or \method{notifyAll()} call for the -same condition variable in another thread, or until the optional -timeout occurs. Once awakened or timed out, it re-acquires the lock -and returns. - -When the \var{timeout} argument is present and not \code{None}, it -should be a floating point number specifying a timeout for the -operation in seconds (or fractions thereof). - -When the underlying lock is an \class{RLock}, it is not released using -its \method{release()} method, since this may not actually unlock the -lock when it was acquired multiple times recursively. Instead, an -internal interface of the \class{RLock} class is used, which really -unlocks it even when it has been recursively acquired several times. -Another internal interface is then used to restore the recursion level -when the lock is reacquired. -\end{methoddesc} - -\begin{methoddesc}{notify}{} -Wake up a thread waiting on this condition, if any. Wait until -notified or until a timeout occurs. If the calling thread has not -acquired the lock when this method is called, a -\exception{RuntimeError} is raised. - -This method wakes up one of the threads waiting for the condition -variable, if any are waiting; it is a no-op if no threads are waiting. - -The current implementation wakes up exactly one thread, if any are -waiting. However, it's not safe to rely on this behavior. A future, -optimized implementation may occasionally wake up more than one -thread. - -Note: the awakened thread does not actually return from its -\method{wait()} call until it can reacquire the lock. Since -\method{notify()} does not release the lock, its caller should. -\end{methoddesc} - -\begin{methoddesc}{notifyAll}{} -Wake up all threads waiting on this condition. This method acts like -\method{notify()}, but wakes up all waiting threads instead of one. If -the calling thread has not acquired the lock when this method is -called, a \exception{RuntimeError} is raised. -\end{methoddesc} - - -\subsection{Semaphore Objects \label{semaphore-objects}} - -This is one of the oldest synchronization primitives in the history of -computer science, invented by the early Dutch computer scientist -Edsger W. Dijkstra (he used \method{P()} and \method{V()} instead of -\method{acquire()} and \method{release()}). - -A semaphore manages an internal counter which is decremented by each -\method{acquire()} call and incremented by each \method{release()} -call. The counter can never go below zero; when \method{acquire()} -finds that it is zero, it blocks, waiting until some other thread -calls \method{release()}. - -\begin{classdesc}{Semaphore}{\optional{value}} -The optional argument gives the initial \var{value} for the internal -counter; it defaults to \code{1}. If the \var{value} given is less -than 0, \exception{ValueError} is raised. -\end{classdesc} - -\begin{methoddesc}{acquire}{\optional{blocking}} -Acquire a semaphore. - -When invoked without arguments: if the internal counter is larger than -zero on entry, decrement it by one and return immediately. If it is -zero on entry, block, waiting until some other thread has called -\method{release()} to make it larger than zero. This is done with -proper interlocking so that if multiple \method{acquire()} calls are -blocked, \method{release()} will wake exactly one of them up. The -implementation may pick one at random, so the order in which blocked -threads are awakened should not be relied on. There is no return -value in this case. - -When invoked with \var{blocking} set to true, do the same thing as -when called without arguments, and return true. - -When invoked with \var{blocking} set to false, do not block. If a -call without an argument would block, return false immediately; -otherwise, do the same thing as when called without arguments, and -return true. -\end{methoddesc} - -\begin{methoddesc}{release}{} -Release a semaphore, -incrementing the internal counter by one. When it was zero on -entry and another thread is waiting for it to become larger -than zero again, wake up that thread. -\end{methoddesc} - - -\subsubsection{\class{Semaphore} Example \label{semaphore-examples}} - -Semaphores are often used to guard resources with limited capacity, for -example, a database server. In any situation where the size of the resource -size is fixed, you should use a bounded semaphore. Before spawning any -worker threads, your main thread would initialize the semaphore: - -\begin{verbatim} -maxconnections = 5 -... -pool_sema = BoundedSemaphore(value=maxconnections) -\end{verbatim} - -Once spawned, worker threads call the semaphore's acquire and release -methods when they need to connect to the server: - -\begin{verbatim} -pool_sema.acquire() -conn = connectdb() -... use connection ... -conn.close() -pool_sema.release() -\end{verbatim} - -The use of a bounded semaphore reduces the chance that a programming error -which causes the semaphore to be released more than it's acquired will go -undetected. - - -\subsection{Event Objects \label{event-objects}} - -This is one of the simplest mechanisms for communication between -threads: one thread signals an event and other threads wait for it. - -An event object manages an internal flag that can be set to true with -the \method{set()} method and reset to false with the \method{clear()} -method. The \method{wait()} method blocks until the flag is true. - - -\begin{classdesc}{Event}{} -The internal flag is initially false. -\end{classdesc} - -\begin{methoddesc}{isSet}{} -Return true if and only if the internal flag is true. -\end{methoddesc} - -\begin{methoddesc}{set}{} -Set the internal flag to true. -All threads waiting for it to become true are awakened. -Threads that call \method{wait()} once the flag is true will not block -at all. -\end{methoddesc} - -\begin{methoddesc}{clear}{} -Reset the internal flag to false. -Subsequently, threads calling \method{wait()} will block until -\method{set()} is called to set the internal flag to true again. -\end{methoddesc} - -\begin{methoddesc}{wait}{\optional{timeout}} -Block until the internal flag is true. -If the internal flag is true on entry, return immediately. Otherwise, -block until another thread calls \method{set()} to set the flag to -true, or until the optional timeout occurs. - -When the timeout argument is present and not \code{None}, it should be a -floating point number specifying a timeout for the operation in -seconds (or fractions thereof). -\end{methoddesc} - - -\subsection{Thread Objects \label{thread-objects}} - -This class represents an activity that is run in a separate thread -of control. There are two ways to specify the activity: by -passing a callable object to the constructor, or by overriding the -\method{run()} method in a subclass. No other methods (except for the -constructor) should be overridden in a subclass. In other words, -\emph{only} override the \method{__init__()} and \method{run()} -methods of this class. - -Once a thread object is created, its activity must be started by -calling the thread's \method{start()} method. This invokes the -\method{run()} method in a separate thread of control. - -Once the thread's activity is started, the thread is considered -'alive'. It stops being alive when its \method{run()} method terminates --- either normally, or by raising an unhandled exception. The -\method{isAlive()} method tests whether the thread is alive. - -Other threads can call a thread's \method{join()} method. This blocks -the calling thread until the thread whose \method{join()} method is -called is terminated. - -A thread has a name. The name can be passed to the constructor, -set with the \method{setName()} method, and retrieved with the -\method{getName()} method. - -A thread can be flagged as a ``daemon thread''. The significance -of this flag is that the entire Python program exits when only -daemon threads are left. The initial value is inherited from the -creating thread. The flag can be set with the \method{setDaemon()} -method and retrieved with the \method{isDaemon()} method. - -There is a ``main thread'' object; this corresponds to the -initial thread of control in the Python program. It is not a -daemon thread. - -There is the possibility that ``dummy thread objects'' are created. -These are thread objects corresponding to ``alien threads'', which -are threads of control started outside the threading module, such as -directly from C code. Dummy thread objects have limited -functionality; they are always considered alive and daemonic, and -cannot be \method{join()}ed. They are never deleted, since it is -impossible to detect the termination of alien threads. - - -\begin{classdesc}{Thread}{group=None, target=None, name=None, - args=(), kwargs=\{\}} -This constructor should always be called with keyword -arguments. Arguments are: - -\var{group} should be \code{None}; reserved for future extension when -a \class{ThreadGroup} class is implemented. - -\var{target} is the callable object to be invoked by the -\method{run()} method. Defaults to \code{None}, meaning nothing is -called. - -\var{name} is the thread name. By default, a unique name is -constructed of the form ``Thread-\var{N}'' where \var{N} is a small -decimal number. - -\var{args} is the argument tuple for the target invocation. Defaults -to \code{()}. - -\var{kwargs} is a dictionary of keyword arguments for the target -invocation. Defaults to \code{\{\}}. - -If the subclass overrides the constructor, it must make sure -to invoke the base class constructor (\code{Thread.__init__()}) -before doing anything else to the thread. -\end{classdesc} - -\begin{methoddesc}{start}{} -Start the thread's activity. - -It must be called at most once per thread object. It arranges for the -object's \method{run()} method to be invoked in a separate thread of -control. - -This method will raise a \exception{RuntimeException} if called more -than once on the same thread object. -\end{methoddesc} - -\begin{methoddesc}{run}{} -Method representing the thread's activity. - -You may override this method in a subclass. The standard -\method{run()} method invokes the callable object passed to the -object's constructor as the \var{target} argument, if any, with -sequential and keyword arguments taken from the \var{args} and -\var{kwargs} arguments, respectively. -\end{methoddesc} - -\begin{methoddesc}{join}{\optional{timeout}} -Wait until the thread terminates. -This blocks the calling thread until the thread whose \method{join()} -method is called terminates -- either normally or through an -unhandled exception -- or until the optional timeout occurs. - -When the \var{timeout} argument is present and not \code{None}, it -should be a floating point number specifying a timeout for the -operation in seconds (or fractions thereof). As \method{join()} always -returns \code{None}, you must call \method{isAlive()} to decide whether -a timeout happened. - -When the \var{timeout} argument is not present or \code{None}, the -operation will block until the thread terminates. - -A thread can be \method{join()}ed many times. - -\method{join()} may throw a \exception{RuntimeError}, if an attempt is -made to join the current thread as that would cause a deadlock. It is -also an error to \method{join()} a thread before it has been started -and attempts to do so raises same exception. -\end{methoddesc} - -\begin{methoddesc}{getName}{} -Return the thread's name. -\end{methoddesc} - -\begin{methoddesc}{setName}{name} -Set the thread's name. - -The name is a string used for identification purposes only. -It has no semantics. Multiple threads may be given the same -name. The initial name is set by the constructor. -\end{methoddesc} - -\begin{methoddesc}{isAlive}{} -Return whether the thread is alive. - -Roughly, a thread is alive from the moment the \method{start()} method -returns until its \method{run()} method terminates. The module -function \function{enumerate()} returns a list of all alive threads. -\end{methoddesc} - -\begin{methoddesc}{isDaemon}{} -Return the thread's daemon flag. -\end{methoddesc} - -\begin{methoddesc}{setDaemon}{daemonic} -Set the thread's daemon flag to the Boolean value \var{daemonic}. -This must be called before \method{start()} is called, otherwise -\exception{RuntimeError} is raised. - -The initial value is inherited from the creating thread. - -The entire Python program exits when no alive non-daemon threads are -left. -\end{methoddesc} - - -\subsection{Timer Objects \label{timer-objects}} - -This class represents an action that should be run only after a -certain amount of time has passed --- a timer. \class{Timer} is a -subclass of \class{Thread} and as such also functions as an example of -creating custom threads. - -Timers are started, as with threads, by calling their \method{start()} -method. The timer can be stopped (before its action has begun) by -calling the \method{cancel()} method. The interval the timer will -wait before executing its action may not be exactly the same as the -interval specified by the user. - -For example: -\begin{verbatim} -def hello(): - print "hello, world" - -t = Timer(30.0, hello) -t.start() # after 30 seconds, "hello, world" will be printed -\end{verbatim} - -\begin{classdesc}{Timer}{interval, function, args=[], kwargs=\{\}} -Create a timer that will run \var{function} with arguments \var{args} and -keyword arguments \var{kwargs}, after \var{interval} seconds have passed. -\end{classdesc} - -\begin{methoddesc}{cancel}{} -Stop the timer, and cancel the execution of the timer's action. This -will only work if the timer is still in its waiting stage. -\end{methoddesc} - -\subsection{Using locks, conditions, and semaphores in the \keyword{with} -statement \label{with-locks}} - -All of the objects provided by this module that have \method{acquire()} and -\method{release()} methods can be used as context managers for a \keyword{with} -statement. The \method{acquire()} method will be called when the block is -entered, and \method{release()} will be called when the block is exited. - -Currently, \class{Lock}, \class{RLock}, \class{Condition}, \class{Semaphore}, -and \class{BoundedSemaphore} objects may be used as \keyword{with} -statement context managers. For example: - -\begin{verbatim} -from __future__ import with_statement -import threading - -some_rlock = threading.RLock() - -with some_rlock: - print "some_rlock is locked while this executes" -\end{verbatim} - |