From: Ralph Ronnquist Date: Mon, 24 Apr 2023 05:25:44 +0000 (+1000) Subject: renamings X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=d7e334fda533e0de8cf5bd9f585e7125cb33eb92;p=rrq%2Flsp-utils.git renamings --- diff --git a/lsp-dbus.a.8.adoc b/lsp-dbus.a.8.adoc deleted file mode 100644 index c840c5d..0000000 --- a/lsp-dbus.a.8.adoc +++ /dev/null @@ -1,246 +0,0 @@ -= lsp-dbus.a(8) -:doctype: manpage -:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"} -:BC: *:* - -== NAME - -lsp-dbus.a - Dbus API for newlisp. - -== SYNOPSIS - -.With packnl -packnl _main.lsp_ *-A lsp-misc.a* *-A lsp-dbus.a* - - -.With incore.lsp -(load "incore.lsp") + -(archive "lsp-misc.a") + -(archive "lsp-utils.a") + -(load "lsp-dbus.lsp") - -== DESCRIPTION - -*lsp-dbus.a* implements a newlisp API for Dbus. The module includes a -context _DbusConnection_ that implements the connection/authorization -level and a context _Dbus_ that implements the "object -modelling"/messaging level. - -The source software is divided into a couple of different source files -that are packed together into an _ar_ archive. - -Note that *lsp-dbus.a* depends on _FOOP_ and _prog1_ from *lsp-misc.a*. - -=== lsp-dbus API - -(*load* "lsp-dbus.lsp"):: - -The main file, *lsp-dbus.lsp*, includes connection setup (see -*:initialize* below) and client registration (i.e. issuing the dbus -"Hello():s" message as part of its loading. Currently it connects on -the system bus (only). It also installs the funcion _main-loop_ as -_prompt-event_ function for processing any unsolicited messages from -dbus (so called "signals"). - -==== The Dbus Context - -(*Dbus* _PATH_ [_DESTINATION_]):: - -The _Dbus_ context is used for identifying remote "objects" with the -given _PATH_ and _DESTINATION_ (aka bus name). The resulting _FOOP_ -object provides a proxying channel for invoking methods targeting the -given path on the given bus-name application. When omitted, the -_DESTINATION_ string is obtained from the _PATH_ string following the -convention of chopping the initial "/" and replacing remaining "/" -with ".". -+ -==== -Note that a term like _(Dbus "/org/freedesktop/DBus")_ defines an -identifer for, or pointer to, a remote "dbus object", and it is here -referred to as _PROXY_. The _PATH_ part serves as the object -identifier for dbus while the _DESTINATION_ part is an identfier for -the application that we expect holds the actual "dbus object" for the -given _PATH_. This particular term identifies object path -"/org/freedesktop/DBus" held by the application named -"org.freedesktop.DBus", which belongs to the dbus framewok. - -There is however no central arbitration for paths in dbus. It all -relies on application developers documenting which paths their -applications service and access, and then client applications rely on -using the destination tags for directing their messages to the -intended applications. -==== - -(*:new-path* _PROXY_ _PATH_):: - -The _:new-path_ method clones the FOOP object to dentify the given -_PATH_ for the same destination. - -(*:invoke* _PROXY_ _METHOD_ _ARGUMENTS_ _FLAGS_):: - -The _:invoke_ method performs a Dbus _METHOD_CALL_ handshake for the -gven _PROXY_ using the given _METHOD_, _ARGUMENTS_ and message -_FLAGS_. The function sends a dbus message and then polls for debus -messages until the reply message has arrived. any and all other -messages recevied meanwhile are added to the _pending_ list. -+ -The _METHOD_ is given as a string composed as path, interface, name -and signature -+ -==== -_path:interface.name(signature)_ -==== -+ -The _path:_ component including the colon is optional and taken from -the _PROXY_ by default. The _interface._ component incuding the period -is also optional as per dbus documentation: a method call without -explicit interface results in that the method name is looked up across -all interfaces of the destination path. -+ -The _SIGNATURE_ is the dbus style signature as a character sequence, -where y, b, n, q, i, u, x, t, d and h indicate the basic types BYTE, -BOOLEAN, INT16, UINT16, INT32, UINT32, INT64, UINT64, DOUBLE and FD -respectivly (both BOOLEAN and FD are also UINT32); a indicates -"array"; s, o and g indicate strings of various restrictions; -parentheses and curly braces wrap "struct" signatures, and v indicates -a pair of a data item preceded by its signature. Refer to dbus -documentation for further details. -+ -The given _ARGUMENTS_ is a list structure that must correspond to the -given signature. All number and string values are mapped naturally -into the indicated signatures while arrays, struct and variant -elements should occur as lists: an array is formed from the list of -elements, as is a struct. A variant typed element must occur as the -list of signature and data. See also the MARSHALLING section below. -+ -The optional _FLAGS_ argument is given either a bit mask (number) or a -list of the _Dbus_ context symbols _NO_REPLY_EXPECTED_, -_NO_AUTO_START_ and _ALLOW_INTERACTIVE_AUTHORIZATION_. Each of these -correspond to a bit position in the _FLAGS_ mask and they are combined -with bit-OR. Refer to dbus documentation for further details. -+ -.Some :invoke usage examples ----- -(:invoke Dbus:ROOT "RequestName(su)" '("my.client" 0)) - -(:invoke Dbus:ROOT "GetNameOwner(s)" '("org.bluez" 0)) - -(setf BT (Dbus "/" "org.bluez")) -(:invoke BT "GetManagedObjects()") -(Dbus:process-pending) ----- -+ -Note "org.bluez" here provides the "GetManagedObjects()" method of -interface "org.freedesktop.ObjectManager" unambiguously on the root -path, "/", rather than its bus name path "/org/bluez". -+ -While this process is waiting for the _METHOD_CALL_ reply it may -receive signal messsages from _dbus_. These will be added to the list -of "pending callbacks" that is processed via the _process-all-pending_ -function, either via an explicit call following the handshake or -"automagically" as part of the _main-loop_ function that gets -installed as as _prompt-event_ function. -+ -.Return value: -[caption=""] -==== -The return value of *:invoke* is the METHOD_REPLY message reduced into -an association list of the headers (with the _Dbus_ header symbols as -keys) extended with the method return value as a list wrapped into a -final association that is keyed by the empty string. - -In other words, the template for using *:invoke* may look like the -following: ----- -(if (:invoke ...) ($it -1 -1 -1)) ----- -==== - -(*Dbus:process-all-pending*):: - -The _process-all-pending_ function processes all pending signal -messages by invoking their associated handler functions. - -(*prompt-event Dbus:main-loop*):: - -The _main-loop_ function is set up as _prompt-event_ function for a -combined _net-select_ on both stdin and the dbus socket as well as to -process all pending signal messages. Any input from dbus, which are -signal messages, are added to the pending list, which also is -processed one message at a time until empty. -+ -Note that newlisp uses readline for input but that this is not -activated in _main-loop_. Therefore line editing is not available -immediately. However the operator may use ^D to leave the main-loop -and enter the "normal" command line input state for a single line -input (with line editing), or an initial newline for multi-line input -that is "submitted" by means of two newlines. - -(*:handler* _OBJ_ _KEY_ _HANDLER_):: - -This function registers a handler callback for a key that is a string -composed as "path:interface.member(signature)". The handler function -takes a single argument, which is the list of unmarshalled actual call -arguments. - -==== The DbusConnection Context - -(*DbusConnection* _PATH):: - -The _DbusConnection_ context is a FOOP implementation intended for the -dbus socket connection. Each _(DbusConnection PATH)_ is intended to be -like a real object that contains state, namely the opened socket file -descriptor, the connection name given to it by DBus on connection and -and the messaging serial. - -(*:serial++* _OBJECT_):: - -This method increments the serial of the given object. - -(*:open-socket* _OBJECT_):: - -This method opens the path and assignes the socket file descriptor of -the given object. Before that though, if the socket file descriptor is -non-negative then that file descriptor is closed before opening the -object's path. - -(*:read-message* _OBJECT_):: - -This method reads the next message by reading data from the socket -successively while there's something to read within a millisecond. - -(*:handshake* _OBJECT_ _MESSAGE_ [_PATTERN_]):: - -This method performs a "raw" text-based handshake on the connection, -which means to send the given message and then read and return the -response message. If a _PATTERN_ is given, then the response must -match the pattern (assigning the automatic variables $1 etc according -to the pattern). The method returns nil if the given pattern is not -matched. Note that this method is used only during connection setup -and dbus communication uses its own marshalling subsequently. - -(*:initialize* _OBJECT_ [_USER_]):: - -This method performs the connection set up including the very first -newline and the subsequent AUTH handshake. It ends with the connection -in "BEGIN" mode and returns the received connection name. - -=== MARSHALLING - -dbus documentation uses the terms "marshalling" and "unmarshalling" -for the translations of data from/to program data to/from dbus message -bytes. The data in newlisp mapped straight-forwardly with the special -note that both "struct" and "array" are held as lists in newlisp. To -that end, the data for the variant type signature must be wrapped into -an extra list of the format _(signature value)_ with explcit dbus -signature string. However, such wrapping does not take place upon -unmarshalling. - - -== SEE ALSO - -*newlisp*, *packnl*, *incore.lsp* - -== AUTHOR - -Ralph Ronnquist diff --git a/lsp-dbus/lsp-dbus.a.8.adoc b/lsp-dbus/lsp-dbus.a.8.adoc new file mode 100644 index 0000000..c840c5d --- /dev/null +++ b/lsp-dbus/lsp-dbus.a.8.adoc @@ -0,0 +1,246 @@ += lsp-dbus.a(8) +:doctype: manpage +:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"} +:BC: *:* + +== NAME + +lsp-dbus.a - Dbus API for newlisp. + +== SYNOPSIS + +.With packnl +packnl _main.lsp_ *-A lsp-misc.a* *-A lsp-dbus.a* + + +.With incore.lsp +(load "incore.lsp") + +(archive "lsp-misc.a") + +(archive "lsp-utils.a") + +(load "lsp-dbus.lsp") + +== DESCRIPTION + +*lsp-dbus.a* implements a newlisp API for Dbus. The module includes a +context _DbusConnection_ that implements the connection/authorization +level and a context _Dbus_ that implements the "object +modelling"/messaging level. + +The source software is divided into a couple of different source files +that are packed together into an _ar_ archive. + +Note that *lsp-dbus.a* depends on _FOOP_ and _prog1_ from *lsp-misc.a*. + +=== lsp-dbus API + +(*load* "lsp-dbus.lsp"):: + +The main file, *lsp-dbus.lsp*, includes connection setup (see +*:initialize* below) and client registration (i.e. issuing the dbus +"Hello():s" message as part of its loading. Currently it connects on +the system bus (only). It also installs the funcion _main-loop_ as +_prompt-event_ function for processing any unsolicited messages from +dbus (so called "signals"). + +==== The Dbus Context + +(*Dbus* _PATH_ [_DESTINATION_]):: + +The _Dbus_ context is used for identifying remote "objects" with the +given _PATH_ and _DESTINATION_ (aka bus name). The resulting _FOOP_ +object provides a proxying channel for invoking methods targeting the +given path on the given bus-name application. When omitted, the +_DESTINATION_ string is obtained from the _PATH_ string following the +convention of chopping the initial "/" and replacing remaining "/" +with ".". ++ +==== +Note that a term like _(Dbus "/org/freedesktop/DBus")_ defines an +identifer for, or pointer to, a remote "dbus object", and it is here +referred to as _PROXY_. The _PATH_ part serves as the object +identifier for dbus while the _DESTINATION_ part is an identfier for +the application that we expect holds the actual "dbus object" for the +given _PATH_. This particular term identifies object path +"/org/freedesktop/DBus" held by the application named +"org.freedesktop.DBus", which belongs to the dbus framewok. + +There is however no central arbitration for paths in dbus. It all +relies on application developers documenting which paths their +applications service and access, and then client applications rely on +using the destination tags for directing their messages to the +intended applications. +==== + +(*:new-path* _PROXY_ _PATH_):: + +The _:new-path_ method clones the FOOP object to dentify the given +_PATH_ for the same destination. + +(*:invoke* _PROXY_ _METHOD_ _ARGUMENTS_ _FLAGS_):: + +The _:invoke_ method performs a Dbus _METHOD_CALL_ handshake for the +gven _PROXY_ using the given _METHOD_, _ARGUMENTS_ and message +_FLAGS_. The function sends a dbus message and then polls for debus +messages until the reply message has arrived. any and all other +messages recevied meanwhile are added to the _pending_ list. ++ +The _METHOD_ is given as a string composed as path, interface, name +and signature ++ +==== +_path:interface.name(signature)_ +==== ++ +The _path:_ component including the colon is optional and taken from +the _PROXY_ by default. The _interface._ component incuding the period +is also optional as per dbus documentation: a method call without +explicit interface results in that the method name is looked up across +all interfaces of the destination path. ++ +The _SIGNATURE_ is the dbus style signature as a character sequence, +where y, b, n, q, i, u, x, t, d and h indicate the basic types BYTE, +BOOLEAN, INT16, UINT16, INT32, UINT32, INT64, UINT64, DOUBLE and FD +respectivly (both BOOLEAN and FD are also UINT32); a indicates +"array"; s, o and g indicate strings of various restrictions; +parentheses and curly braces wrap "struct" signatures, and v indicates +a pair of a data item preceded by its signature. Refer to dbus +documentation for further details. ++ +The given _ARGUMENTS_ is a list structure that must correspond to the +given signature. All number and string values are mapped naturally +into the indicated signatures while arrays, struct and variant +elements should occur as lists: an array is formed from the list of +elements, as is a struct. A variant typed element must occur as the +list of signature and data. See also the MARSHALLING section below. ++ +The optional _FLAGS_ argument is given either a bit mask (number) or a +list of the _Dbus_ context symbols _NO_REPLY_EXPECTED_, +_NO_AUTO_START_ and _ALLOW_INTERACTIVE_AUTHORIZATION_. Each of these +correspond to a bit position in the _FLAGS_ mask and they are combined +with bit-OR. Refer to dbus documentation for further details. ++ +.Some :invoke usage examples +---- +(:invoke Dbus:ROOT "RequestName(su)" '("my.client" 0)) + +(:invoke Dbus:ROOT "GetNameOwner(s)" '("org.bluez" 0)) + +(setf BT (Dbus "/" "org.bluez")) +(:invoke BT "GetManagedObjects()") +(Dbus:process-pending) +---- ++ +Note "org.bluez" here provides the "GetManagedObjects()" method of +interface "org.freedesktop.ObjectManager" unambiguously on the root +path, "/", rather than its bus name path "/org/bluez". ++ +While this process is waiting for the _METHOD_CALL_ reply it may +receive signal messsages from _dbus_. These will be added to the list +of "pending callbacks" that is processed via the _process-all-pending_ +function, either via an explicit call following the handshake or +"automagically" as part of the _main-loop_ function that gets +installed as as _prompt-event_ function. ++ +.Return value: +[caption=""] +==== +The return value of *:invoke* is the METHOD_REPLY message reduced into +an association list of the headers (with the _Dbus_ header symbols as +keys) extended with the method return value as a list wrapped into a +final association that is keyed by the empty string. + +In other words, the template for using *:invoke* may look like the +following: +---- +(if (:invoke ...) ($it -1 -1 -1)) +---- +==== + +(*Dbus:process-all-pending*):: + +The _process-all-pending_ function processes all pending signal +messages by invoking their associated handler functions. + +(*prompt-event Dbus:main-loop*):: + +The _main-loop_ function is set up as _prompt-event_ function for a +combined _net-select_ on both stdin and the dbus socket as well as to +process all pending signal messages. Any input from dbus, which are +signal messages, are added to the pending list, which also is +processed one message at a time until empty. ++ +Note that newlisp uses readline for input but that this is not +activated in _main-loop_. Therefore line editing is not available +immediately. However the operator may use ^D to leave the main-loop +and enter the "normal" command line input state for a single line +input (with line editing), or an initial newline for multi-line input +that is "submitted" by means of two newlines. + +(*:handler* _OBJ_ _KEY_ _HANDLER_):: + +This function registers a handler callback for a key that is a string +composed as "path:interface.member(signature)". The handler function +takes a single argument, which is the list of unmarshalled actual call +arguments. + +==== The DbusConnection Context + +(*DbusConnection* _PATH):: + +The _DbusConnection_ context is a FOOP implementation intended for the +dbus socket connection. Each _(DbusConnection PATH)_ is intended to be +like a real object that contains state, namely the opened socket file +descriptor, the connection name given to it by DBus on connection and +and the messaging serial. + +(*:serial++* _OBJECT_):: + +This method increments the serial of the given object. + +(*:open-socket* _OBJECT_):: + +This method opens the path and assignes the socket file descriptor of +the given object. Before that though, if the socket file descriptor is +non-negative then that file descriptor is closed before opening the +object's path. + +(*:read-message* _OBJECT_):: + +This method reads the next message by reading data from the socket +successively while there's something to read within a millisecond. + +(*:handshake* _OBJECT_ _MESSAGE_ [_PATTERN_]):: + +This method performs a "raw" text-based handshake on the connection, +which means to send the given message and then read and return the +response message. If a _PATTERN_ is given, then the response must +match the pattern (assigning the automatic variables $1 etc according +to the pattern). The method returns nil if the given pattern is not +matched. Note that this method is used only during connection setup +and dbus communication uses its own marshalling subsequently. + +(*:initialize* _OBJECT_ [_USER_]):: + +This method performs the connection set up including the very first +newline and the subsequent AUTH handshake. It ends with the connection +in "BEGIN" mode and returns the received connection name. + +=== MARSHALLING + +dbus documentation uses the terms "marshalling" and "unmarshalling" +for the translations of data from/to program data to/from dbus message +bytes. The data in newlisp mapped straight-forwardly with the special +note that both "struct" and "array" are held as lists in newlisp. To +that end, the data for the variant type signature must be wrapped into +an extra list of the format _(signature value)_ with explcit dbus +signature string. However, such wrapping does not take place upon +unmarshalling. + + +== SEE ALSO + +*newlisp*, *packnl*, *incore.lsp* + +== AUTHOR + +Ralph Ronnquist diff --git a/lsp-misc.a.8.adoc b/lsp-misc.a.8.adoc deleted file mode 100644 index 7f8a5d0..0000000 --- a/lsp-misc.a.8.adoc +++ /dev/null @@ -1,138 +0,0 @@ -= lsp-misc.a(8) -:doctype: manpage -:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"} - -== NAME - -lsp-misc.a - Misceallaneous useful functions. - -== SYNOPSIS - -.With packnl (example) -packnl _main.lsp_ *-A lsp-misc.a* - - -.With incore.lsp -(load "incore.lsp") + -(archive "lsp-misc.a") + -(load "misc.lsp") - -== DESCRIPTION - -*lsp-misc.a* provides a few global utility functions. - -=== misc.lsp API - -(prog1 [_term_]*):: - -The *prog1* function is like a *begin* function except that it returns -the value of the first term rather than the last. - -(die _N_ [_term_]*):: - -The *die* function printes to stderr the join of term values as -strings with space separation, and if _N_ is a number, then the -function exits the program with that return code. -+ -.Example of stderr logging -(die nil 'This "is" 'printed "to stderr") - -(octal-byte _B_):: -Print binary byte as octal or as ASCII character [32-126]. - -(octals-string _S_):: -Print string as a succesion of +octal-byte+. - -(human-byte _B_):: -Return byte code as printable (string) or as code (number). - -(human-bytes _BL_):: - -Return a list of human-byte elements from a list of byte codes but -also joining consecutive string elements to form packed strings. - -=== foop.lsp API - -This newlisp module provides Functional Object-Oriented Programming -(FOOP) modelling support. - -FOOP is an abstraction overlay using the newlisp context notion as a -simile to the _class_ notion in genuine object-oriented programming -languages. This is set out in newlisp by means of the representation -principle that an instance of a FOOP "class" (i.e. context) is a list -headed by the context itself, and followed by the "member values". - -FOOP further includes by the "method invocation" syntax where a -function is preceded by ':' and then followed by the instance -concerned before actual function arguments. That instance is then -stoved away as implicitly available via the (self) function, and the -member values accessible via index, e.g. the term (self 3) refers to -the third member of the instance. The self references are -destructively assignable with setf. - -This modelling support adds member name declaration together with -automatic getter and setter defintions. The (FOOP ...) term is used -for declaring member names in order. For example: - -(FOOP [_name_]):: - -*FOOP* is like a language extension to declare the field names of a -FOOP class, and thereby gain "get" and "set" functions generated with -the respective naming formats (:%name obj) and (:!name obj value). - -.illustration ----- -(context 'MAIN:EX) -(FOOP here there more) -(define (EX HERE THERE MORE) (list (context) HERE THERE MORE)) - -(context MAIN) -(setf A (EX 1 2 3)) ---> A = (EX 1 2 3) -(:!there A 4) ---> A = (EX 1 4 3) ----- - -=== mmap.lsp API - -This newlisp module implements a small FOOP model based memory mapping -API that links in the _libc6_ functions _mmap_, _munmap_, _msync_ and -_lseek_. - -(*MMap* _FD_ _LENGTH_ [_OFFSET_ [_PROT_]]):: - -This function creates a FOOP object that represents the memory mapping -of the given file descriptor. _FD_ may be the pathname string of a -file to memory map or an already opened file descriptor. The MMap -object represents the memory block starting at (:%base) and (%len) -bytes in length where the file is memory mapped. -+ -.Access example (from test.lsp) -[caption=""] ----- -(println (setf X (MMap "mmap.lsp"))) -(println (get-string (:%base X))) ----- -+ -Note that only a plain text file would be accessed with _get-string_. -A binary file would rather be accessed with _unpack_. The memory -mapping provides read-only "random access" to the file content. -+ -To set up read-write acces requires an _OFFSET_ and the _PROT_ -argument 0x3, and writing should be accompanied by _MMap:msync_ calls -so as to synchronize with the backing file. -+ -The FOOP object includes get and set methods for the fields (in -order): _base_, _len_, _prot_, _flags_, _fd_ and _offset_. - -=== test.lsp - -This file is a small test of the MMap memory mapping. - -== SEE ALSO - -*newlisp* - -== AUTHOR - -Ralph Ronnquist diff --git a/lsp-misc/lsp-misc.a.8.adoc b/lsp-misc/lsp-misc.a.8.adoc new file mode 100644 index 0000000..7f8a5d0 --- /dev/null +++ b/lsp-misc/lsp-misc.a.8.adoc @@ -0,0 +1,138 @@ += lsp-misc.a(8) +:doctype: manpage +:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"} + +== NAME + +lsp-misc.a - Misceallaneous useful functions. + +== SYNOPSIS + +.With packnl (example) +packnl _main.lsp_ *-A lsp-misc.a* + + +.With incore.lsp +(load "incore.lsp") + +(archive "lsp-misc.a") + +(load "misc.lsp") + +== DESCRIPTION + +*lsp-misc.a* provides a few global utility functions. + +=== misc.lsp API + +(prog1 [_term_]*):: + +The *prog1* function is like a *begin* function except that it returns +the value of the first term rather than the last. + +(die _N_ [_term_]*):: + +The *die* function printes to stderr the join of term values as +strings with space separation, and if _N_ is a number, then the +function exits the program with that return code. ++ +.Example of stderr logging +(die nil 'This "is" 'printed "to stderr") + +(octal-byte _B_):: +Print binary byte as octal or as ASCII character [32-126]. + +(octals-string _S_):: +Print string as a succesion of +octal-byte+. + +(human-byte _B_):: +Return byte code as printable (string) or as code (number). + +(human-bytes _BL_):: + +Return a list of human-byte elements from a list of byte codes but +also joining consecutive string elements to form packed strings. + +=== foop.lsp API + +This newlisp module provides Functional Object-Oriented Programming +(FOOP) modelling support. + +FOOP is an abstraction overlay using the newlisp context notion as a +simile to the _class_ notion in genuine object-oriented programming +languages. This is set out in newlisp by means of the representation +principle that an instance of a FOOP "class" (i.e. context) is a list +headed by the context itself, and followed by the "member values". + +FOOP further includes by the "method invocation" syntax where a +function is preceded by ':' and then followed by the instance +concerned before actual function arguments. That instance is then +stoved away as implicitly available via the (self) function, and the +member values accessible via index, e.g. the term (self 3) refers to +the third member of the instance. The self references are +destructively assignable with setf. + +This modelling support adds member name declaration together with +automatic getter and setter defintions. The (FOOP ...) term is used +for declaring member names in order. For example: + +(FOOP [_name_]):: + +*FOOP* is like a language extension to declare the field names of a +FOOP class, and thereby gain "get" and "set" functions generated with +the respective naming formats (:%name obj) and (:!name obj value). + +.illustration +---- +(context 'MAIN:EX) +(FOOP here there more) +(define (EX HERE THERE MORE) (list (context) HERE THERE MORE)) + +(context MAIN) +(setf A (EX 1 2 3)) +--> A = (EX 1 2 3) +(:!there A 4) +--> A = (EX 1 4 3) +---- + +=== mmap.lsp API + +This newlisp module implements a small FOOP model based memory mapping +API that links in the _libc6_ functions _mmap_, _munmap_, _msync_ and +_lseek_. + +(*MMap* _FD_ _LENGTH_ [_OFFSET_ [_PROT_]]):: + +This function creates a FOOP object that represents the memory mapping +of the given file descriptor. _FD_ may be the pathname string of a +file to memory map or an already opened file descriptor. The MMap +object represents the memory block starting at (:%base) and (%len) +bytes in length where the file is memory mapped. ++ +.Access example (from test.lsp) +[caption=""] +---- +(println (setf X (MMap "mmap.lsp"))) +(println (get-string (:%base X))) +---- ++ +Note that only a plain text file would be accessed with _get-string_. +A binary file would rather be accessed with _unpack_. The memory +mapping provides read-only "random access" to the file content. ++ +To set up read-write acces requires an _OFFSET_ and the _PROT_ +argument 0x3, and writing should be accompanied by _MMap:msync_ calls +so as to synchronize with the backing file. ++ +The FOOP object includes get and set methods for the fields (in +order): _base_, _len_, _prot_, _flags_, _fd_ and _offset_. + +=== test.lsp + +This file is a small test of the MMap memory mapping. + +== SEE ALSO + +*newlisp* + +== AUTHOR + +Ralph Ronnquist