Changeset 15308


Ignore:
Timestamp:
06/04/20 08:25:16 (6 months ago)
Author:
Mark Evenson
Message:

nio: documentation for extensions to CL:MAKE-ARRAY

Location:
trunk/abcl/doc/manual
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/abcl/doc/manual/abcl.sty

    r13853 r15308  
    4242\makeindex
    4343
     44\usepackage{enumitem}
     45
    4446\ProvidesPackage{abcl}
    4547
  • trunk/abcl/doc/manual/abcl.tex

    r15280 r15308  
    908908\chapter{Beyond ANSI}
    909909
    910 Naturally, in striving to be a useful contemporary \textsc{Common Lisp}
    911 implementation, \textsc{ABCL} endeavors to include extensions beyond the ANSI
    912 specification which are either widely adopted or are especially useful
    913 in working with the hosting \textsc{JVM}.
     910Naturally, in striving to be a useful contemporary \textsc{Common
     911  Lisp} implementation, \textsc{ABCL} endeavors to include extensions
     912beyond the ANSI specification which are either widely adopted or are
     913especially useful in working with the hosting \textsc{JVM}.  This
     914chapter documents such extensions beyond ANSI conformation.
    914915
    915916\section{Compiler to Java Virtual Machine Bytecode}
     
    13931394\section{ASDF}
    13941395
    1395 asdf-3.3.3 (see \cite{asdf}) is packaged as core component of \textsc{ABCL},
     1396asdf-3.3.4 (see \cite{asdf}) is packaged as core component of \textsc{ABCL},
    13961397but not initialized by default, as it relies on the \textsc{CLOS} subsystem
    13971398which can take a bit of time to start \footnote{While this time is
     
    14051406CL-USER> (require :asdf)
    14061407\end{listing-lisp}
     1408
     1409\section{Extension to CL:MAKE-ARRAY}
     1410
     1411With the \code{:nio} feature is present\footnote{Available starting in
     1412abcl-1.7.0 and indicated by the presence of \code{:nio} in
     1413\code{cl:*features*}}, the implementation adds two keyword arguments
     1414to \code{cl:make-array}, viz. \code{:nio-buffer} and
     1415\code{:nio-direct}.
     1416
     1417With the \code{:nio-buffer} keyword, the user is able to pass
     1418instances of of \code{java.nio.ByteBuffer} and its subclasses for the
     1419storage of vectors and arrays specialized on the byte-vector
     1420types satisfying
     1421
     1422\begin{listing-lisp}
     1423  (or
     1424    (unsigned-byte 8)
     1425    (unsigned-byte 16)
     1426    (unsigned-byte 32))
     1427\end{listing-lisp}
     1428
     1429As an example, the following would use the \code{:nio-buffer} as
     1430follows to create a 16 byte vector using the created byte-buffer for
     1431storage:
     1432
     1433\begin{listing-lisp}
     1434  (let* ((length 16)
     1435         (byte-buffer (java:jstatic "allocate" "java.nio.ByteBuffer" length)))
     1436    (make-array length :element-type '(unsigned-byte 8) :nio-buffer byte-buffer))
     1437\end{listing-lisp}
     1438
     1439This feature is available in CFFI\footnote{Available at runtime via
     1440\textsc{Quicklisp}} via
     1441\code{CFFI-SYS:MAKE-SHAREABLE-BYTE-VECTOR}\footnote{Implemented in
     1442\url{https://github.com/cffi/cffi/commit/47136ad9a97c2df98dbcd13a068e14489ced5b03}}
     1443
     1444
     1445\begin{description}[style=nextline]
     1446
     1447\item[\code{:nio-buffer NIO-BUFFER}]
     1448
     1449Initializes the contents of the new vector or array with the contents
     1450of \code{NIO-BUFFER} which needs to be a reference to a
     1451\code{java-object} of class \code{java.nio.ByteBuffer}.
     1452
     1453\item[\code{:nio-direct NIO-DIRECT-P}]
     1454
     1455When \code{NIO-DIRECT-P} is non-\code{nil}, constructs a
     1456java.nio.Buffer as a ``direct'' buffer.  The buffers returned by this
     1457method typically have somewhat higher allocation and deallocation
     1458costs than non-direct buffers. The contents of direct buffers may
     1459reside outside of the normal garbage-collected heap, and so their
     1460impact upon the memory footprint of an application might not be
     1461obvious. It is therefore recommended that direct buffers be allocated
     1462primarily for large, long-lived buffers that are subject to the
     1463underlying system's native I/O operations. In general it is best to
     1464allocate direct buffers only when they yield a measureable gain in
     1465program performance.
     1466
     1467\end{description}
     1468
    14071469
    14081470\chapter{Contrib}
Note: See TracChangeset for help on using the changeset viewer.