diff --git a/.buildinfo b/.buildinfo index 12a14a42f..5961bf457 100644 --- a/.buildinfo +++ b/.buildinfo @@ -1,4 +1,4 @@ # Sphinx build info version 1 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. -config: 582e292e2d15c53fe810804add915320 +config: 2970c865730e9c31a9bae7db6c9ac6c1 tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/.doctrees/asynDriver.doctree b/.doctrees/asynDriver.doctree index 490781ac9..0245cff4c 100644 Binary files a/.doctrees/asynDriver.doctree and b/.doctrees/asynDriver.doctree differ diff --git a/.doctrees/asynPortClient.doctree b/.doctrees/asynPortClient.doctree index 3438c7d5d..3867a63b7 100644 Binary files a/.doctrees/asynPortClient.doctree and b/.doctrees/asynPortClient.doctree differ diff --git a/.doctrees/asynPortDriver.doctree b/.doctrees/asynPortDriver.doctree index cacb94d98..027a64e28 100644 Binary files a/.doctrees/asynPortDriver.doctree and b/.doctrees/asynPortDriver.doctree differ diff --git a/.doctrees/environment.pickle b/.doctrees/environment.pickle index 0bffeb27e..55274bb78 100644 Binary files a/.doctrees/environment.pickle and b/.doctrees/environment.pickle differ diff --git a/HowToDoSerial.html b/HowToDoSerial.html index 1251af09b..f79dab6e9 100644 --- a/HowToDoSerial.html +++ b/HowToDoSerial.html @@ -16,7 +16,7 @@ - + @@ -728,7 +728,7 @@

5.3 Add records to set and check the output voltage and current setpoints

© Copyright 2023, Mark Rivers. - Last updated on 2024-February-05. + Last updated on 2024-May-30.

diff --git a/_sources/asynDriver.rst.txt b/_sources/asynDriver.rst.txt index 35cfe5fec..f98eb9267 100644 --- a/_sources/asynDriver.rst.txt +++ b/_sources/asynDriver.rst.txt @@ -150,7 +150,7 @@ most influential. - Dirk developed StreamDevice, which has a single device support model, but supports arbitrary low level message based drivers, i.e. GPIB, serial, etc. -- **Jun-ichi Odagare** +- **Jun-ichi Odagiri** - Jun-ichi developed NetDev, a system that provides EPICS device support for network based devices. It has a single device support model, but provides a general framework @@ -414,7 +414,7 @@ Queuing services than the current port timeout value this larger timeout from the pasynUser is used instead. - blockProcessCallback is a request to prevent acccess to a device or port by other + blockProcessCallback is a request to prevent access to a device or port by other asynUsers between queueRequests. blockProcessCallback can be called from a processCallback or when the asynUser has no request queued. When called from processCallback blocking starts immediately, otherwise blocking starts the next time processCallback is called. @@ -504,11 +504,11 @@ Interrupt services the request after interruptEnd is called. Many standard interfaces, e.g. asynInt32, provide methods registerInterruptUser, - cancelInterruptUser. These interfaces also provide an auxilliary interface, e.g. + cancelInterruptUser. These interfaces also provide an auxiliary interface, e.g. asynInt32Base, and code which implements registerInterruptUser and cancelInterruptUser. On operating systems like vxWorks or RTEMS interruptStart,interruptEnd MUST NOT - be called from interupt level. + be called from interrupt level. Timestamp services .................. @@ -696,7 +696,7 @@ An asynUser has the following features: - An asynUser is the means by which asynManager manages multiple requests for accessing a port. -- processCallback,which is used by queueRequest described below, is the addresss +- processCallback,which is used by queueRequest described below, is the address of a user supplied callback routine. - timeoutCallback is the address of caller supplied callback that will be called if a queueRequest remains on the queue too long. @@ -803,7 +803,7 @@ asynDriver.h describes the following: - asynStatus - An enum that describes the status returned by many methods. - asynException - An enum that describes exceptions. - asynQueuePriority - An enum that describes the queue priorities. -- asynUser - A struture that contains generic information and is the "handle" for calling most methods. +- asynUser - A structure that contains generic information and is the "handle" for calling most methods. - asynInterface - a structure that describes an interface. - userCallback - a typedef for the user process callback function described above. - exceptionCallback - a typedef for a user callback to be called when exceptions occur. @@ -838,7 +838,7 @@ method is expected to write a message into pasynUser->errorMessage. supplied buffer is too small. Whenever possible, low level drivers should be written so that the user can read input in small pieces. * - asynError - - Some other error occured. + - Some other error occurred. * - asynDisconnected - The request failed because the port is not connected. * - asynDisabled @@ -947,7 +947,7 @@ asynManager:duplicateAsynUser) and asynManager:freeAsynUser. > 0.0 Wait for up to timeout seconds for the I/O to complete - = 0.0 Peform any I/O that can be done without blocking. Return timeout error if + = 0.0 Perform any I/O that can be done without blocking. Return timeout error if no I/O can be done without blocking. < 0.0 Infinite timeout. Wait forever for I/O to complete. @@ -1212,7 +1212,7 @@ This is the main interface for communicating with asynDriver. callback is active when cancelRequest is called than cancelRequest will not return until the callback completes. * - blockProcessCallback / unblockProcessCallback - - blockProcessCallback is a request to prevent acccess to a device or port by other + - blockProcessCallback is a request to prevent access to a device or port by other asynUsers between queueRequests. blockProcessCallback can be called from a processCallback or when the asynUser has no request queued. When called from processCallback blocking starts immediately, otherwise blocking starts the next time processCallback is called. @@ -1321,7 +1321,7 @@ This is the main interface for communicating with asynDriver. supports interrupts. pasynPvt must be the address of a void * that will be given a value by registerInterruptSource. This argument is passed interruptStart and interruptEnd. * - getInterruptPvt - - Any code that wants to call createInterruptNode but does not know the adresss of + - Any code that wants to call createInterruptNode but does not know the address of pasynPvt can find it via this method. The caller must be connected to a device, i.e. must have called connectDevice. If the caller is not connected, getInterruptPvt returns asynError. @@ -1341,7 +1341,7 @@ This is the main interface for communicating with asynDriver. will block forever. * - interruptStart / interruptEnd - The code that implements interrupts is interface dependent. The only service asynManager - provides is a thread-safe implemention of the user list. When the code wants to + provides is a thread-safe implementation of the user list. When the code wants to call the callback specified in the calls to registerInterruptUser, it calls interruptStart to obtain the list of callbacks. When it is done it calls interruptEnd. If any requests are made to addInterruptUser/removeInterruptUser between the calls to interruptStart @@ -2002,7 +2002,7 @@ for: Note that hardware may have registers with smaller sizes, e.g. 16 bit registers. The standard interfaces can still be used by setting the unused bits to 0. -For all of these interfaces a default implementation and a synchronous inplementation +For all of these interfaces a default implementation and a synchronous implementation are provided. Let's use Int32 as an example. - asynInt32 - An interface with methods: read, write, getBounds, registerInterruptUser, @@ -3124,7 +3124,7 @@ asynInterposeFlush ~~~~~~~~~~~~~~~~~~ This can be used to simulate flush processing for asynOctet if the port driver doesn't provide support for flush. It just reads and discards characters until no more characters -arive before timeout seconds have occured. It is started by the shell command: +arrive before timeout seconds have occurred. It is started by the shell command: :: asynInterposeFlushConfig port addr timeout @@ -4749,7 +4749,7 @@ where - priority - In integer specifying the priority of the portThread. A value of 0 - will result in a defalt value being assigned + will result in a default value being assigned - noAutoConnect - Zero or missing indicates that portThread should automatically @@ -5505,7 +5505,8 @@ Example: testAsynIPPortClient cars.uchicago.edu:80 "GET / HTTP/1.0" "\n\n" The example resides in /testAsynPortClientApp. -testAsynPortDriverApp

+testAsynPortDriverApp +~~~~~~~~~~~~~~~~~~~~~ This test demonstrates how to write a driver using the asynPortDriver C++ class. It consists of a simple digital oscilloscope simulator. When the vertical gain changes @@ -5697,7 +5698,7 @@ files for the stream package and for any needed ASYN drivers. There are two ways that this can be done: If you are building your application database definition file from the application -Makefile you specify the aditional database definitions there (uncomment the lines +Makefile you specify the additional database definitions there (uncomment the lines appropriate to your application): :: diff --git a/_sources/asynPortClient.rst.txt b/_sources/asynPortClient.rst.txt index d729de584..7745761e1 100644 --- a/_sources/asynPortClient.rst.txt +++ b/_sources/asynPortClient.rst.txt @@ -44,5 +44,5 @@ port drivers without running an IOC. This currently contains a single test appli testAsynIPPortClient.cpp. This program creates an asynIPPort driver, and uses the command line arguments to set the hostInfo string, a single command string to send to the server, and optionally the input and output EOS. It then prints out the response -from the server. There are 3 example shell scipts that show how to use testAsynIPPortClient +from the server. There are 3 example shell scripts that show how to use testAsynIPPortClient to communicate with a Web server, XPS motor controller, and a telnet host respectively. diff --git a/_sources/asynPortDriver.rst.txt b/_sources/asynPortDriver.rst.txt index 15bc08495..2dbbc7850 100644 --- a/_sources/asynPortDriver.rst.txt +++ b/_sources/asynPortDriver.rst.txt @@ -23,7 +23,7 @@ to this new value. The sequence of operations in the driver can be summarized as #. When operation is complete, call the registered callbacks for each changed parameter. asynPortDriver provides methods to simplify the above sequence, which must be implemented -for each of the often many parameters that the driver supports. Each parameter is +for each of the many parameters that the driver supports. Each parameter is assigned a number, which is the value in the pasynUser->reason field that asyn clients pass to the driver when reading or writing that parameter. asynPortDriver maintains a table of parameter values, associating each parameter number with a diff --git a/_static/basic.css b/_static/basic.css index 30fee9d0f..f316efcb4 100644 --- a/_static/basic.css +++ b/_static/basic.css @@ -4,7 +4,7 @@ * * Sphinx stylesheet -- basic theme. * - * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. * :license: BSD, see LICENSE for details. * */ diff --git a/_static/doctools.js b/_static/doctools.js index d06a71d75..4d67807d1 100644 --- a/_static/doctools.js +++ b/_static/doctools.js @@ -4,7 +4,7 @@ * * Base JavaScript utilities for all Sphinx HTML documentation. * - * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. * :license: BSD, see LICENSE for details. * */ diff --git a/_static/language_data.js b/_static/language_data.js index 250f5665f..367b8ed81 100644 --- a/_static/language_data.js +++ b/_static/language_data.js @@ -5,7 +5,7 @@ * This script contains the language-specific data used by searchtools.js, * namely the list of stopwords, stemmer, scorer and splitter. * - * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. * :license: BSD, see LICENSE for details. * */ @@ -13,7 +13,7 @@ var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; -/* Non-minified version is copied as a separate JS file, is available */ +/* Non-minified version is copied as a separate JS file, if available */ /** * Porter Stemmer diff --git a/_static/searchtools.js b/_static/searchtools.js index 7918c3fab..92da3f8b2 100644 --- a/_static/searchtools.js +++ b/_static/searchtools.js @@ -4,7 +4,7 @@ * * Sphinx JavaScript utilities for the full-text search. * - * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. * :license: BSD, see LICENSE for details. * */ @@ -99,7 +99,7 @@ const _displayItem = (item, searchTerms, highlightTerms) => { .then((data) => { if (data) listItem.appendChild( - Search.makeSearchSummary(data, searchTerms) + Search.makeSearchSummary(data, searchTerms, anchor) ); // highlight search terms in the summary if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js @@ -116,8 +116,8 @@ const _finishSearch = (resultCount) => { ); else Search.status.innerText = _( - `Search finished, found ${resultCount} page(s) matching the search query.` - ); + "Search finished, found ${resultCount} page(s) matching the search query." + ).replace('${resultCount}', resultCount); }; const _displayNextItem = ( results, @@ -137,6 +137,22 @@ const _displayNextItem = ( // search finished, update title and status message else _finishSearch(resultCount); }; +// Helper function used by query() to order search results. +// Each input is an array of [docname, title, anchor, descr, score, filename]. +// Order the results by score (in opposite order of appearance, since the +// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically. +const _orderResultsByScoreThenName = (a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; +}; /** * Default splitQuery function. Can be overridden in ``sphinx.search`` with a @@ -160,13 +176,26 @@ const Search = { _queued_query: null, _pulse_status: -1, - htmlToText: (htmlString) => { + htmlToText: (htmlString, anchor) => { const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); - htmlElement.querySelectorAll(".headerlink").forEach((el) => { el.remove() }); + for (const removalQuery of [".headerlinks", "script", "style"]) { + htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() }); + } + if (anchor) { + const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`); + if (anchorContent) return anchorContent.textContent; + + console.warn( + `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.` + ); + } + + // if anchor not specified or not found, fall back to main content const docContent = htmlElement.querySelector('[role="main"]'); - if (docContent !== undefined) return docContent.textContent; + if (docContent) return docContent.textContent; + console.warn( - "Content block not found. Sphinx search tries to obtain it via '[role=main]'. Could you check your theme or template." + "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template." ); return ""; }, @@ -239,16 +268,7 @@ const Search = { else Search.deferQuery(query); }, - /** - * execute search (requires search index to be loaded) - */ - query: (query) => { - const filenames = Search._index.filenames; - const docNames = Search._index.docnames; - const titles = Search._index.titles; - const allTitles = Search._index.alltitles; - const indexEntries = Search._index.indexentries; - + _parseQuery: (query) => { // stem the search terms and add them to the correct list const stemmer = new Stemmer(); const searchTerms = new Set(); @@ -284,16 +304,32 @@ const Search = { // console.info("required: ", [...searchTerms]); // console.info("excluded: ", [...excludedTerms]); - // array of [docname, title, anchor, descr, score, filename] - let results = []; + return [query, searchTerms, excludedTerms, highlightTerms, objectTerms]; + }, + + /** + * execute search (requires search index to be loaded) + */ + _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // Collect multiple result groups to be sorted separately and then ordered. + // Each is an array of [docname, title, anchor, descr, score, filename]. + const normalResults = []; + const nonMainIndexResults = []; + _removeChildren(document.getElementById("search-progress")); - const queryLower = query.toLowerCase(); + const queryLower = query.toLowerCase().trim(); for (const [title, foundTitles] of Object.entries(allTitles)) { - if (title.toLowerCase().includes(queryLower) && (queryLower.length >= title.length/2)) { + if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) { for (const [file, id] of foundTitles) { let score = Math.round(100 * queryLower.length / title.length) - results.push([ + normalResults.push([ docNames[file], titles[file] !== title ? `${titles[file]} > ${title}` : title, id !== null ? "#" + id : "", @@ -308,46 +344,47 @@ const Search = { // search for explicit entries in index directives for (const [entry, foundEntries] of Object.entries(indexEntries)) { if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { - for (const [file, id] of foundEntries) { - let score = Math.round(100 * queryLower.length / entry.length) - results.push([ + for (const [file, id, isMain] of foundEntries) { + const score = Math.round(100 * queryLower.length / entry.length); + const result = [ docNames[file], titles[file], id ? "#" + id : "", null, score, filenames[file], - ]); + ]; + if (isMain) { + normalResults.push(result); + } else { + nonMainIndexResults.push(result); + } } } } // lookup as object objectTerms.forEach((term) => - results.push(...Search.performObjectSearch(term, objectTerms)) + normalResults.push(...Search.performObjectSearch(term, objectTerms)) ); // lookup as search terms in fulltext - results.push(...Search.performTermsSearch(searchTerms, excludedTerms)); + normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms)); // let the scorer override scores with a custom scoring function - if (Scorer.score) results.forEach((item) => (item[4] = Scorer.score(item))); - - // now sort the results by score (in opposite order of appearance, since the - // display function below uses pop() to retrieve items) and then - // alphabetically - results.sort((a, b) => { - const leftScore = a[4]; - const rightScore = b[4]; - if (leftScore === rightScore) { - // same score: sort alphabetically - const leftTitle = a[1].toLowerCase(); - const rightTitle = b[1].toLowerCase(); - if (leftTitle === rightTitle) return 0; - return leftTitle > rightTitle ? -1 : 1; // inverted is intentional - } - return leftScore > rightScore ? 1 : -1; - }); + if (Scorer.score) { + normalResults.forEach((item) => (item[4] = Scorer.score(item))); + nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item))); + } + + // Sort each group of results by score and then alphabetically by name. + normalResults.sort(_orderResultsByScoreThenName); + nonMainIndexResults.sort(_orderResultsByScoreThenName); + + // Combine the result groups in (reverse) order. + // Non-main index entries are typically arbitrary cross-references, + // so display them after other results. + let results = [...nonMainIndexResults, ...normalResults]; // remove duplicate search results // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept @@ -361,7 +398,12 @@ const Search = { return acc; }, []); - results = results.reverse(); + return results.reverse(); + }, + + query: (query) => { + const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query); + const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms); // for debugging //Search.lastresults = results.slice(); // a copy @@ -466,14 +508,18 @@ const Search = { // add support for partial matches if (word.length > 2) { const escapedWord = _escapeRegExp(word); - Object.keys(terms).forEach((term) => { - if (term.match(escapedWord) && !terms[word]) - arr.push({ files: terms[term], score: Scorer.partialTerm }); - }); - Object.keys(titleTerms).forEach((term) => { - if (term.match(escapedWord) && !titleTerms[word]) - arr.push({ files: titleTerms[word], score: Scorer.partialTitle }); - }); + if (!terms.hasOwnProperty(word)) { + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + } + if (!titleTerms.hasOwnProperty(word)) { + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: titleTerms[term], score: Scorer.partialTitle }); + }); + } } // no match but word was a required one @@ -496,9 +542,8 @@ const Search = { // create the mapping files.forEach((file) => { - if (fileMap.has(file) && fileMap.get(file).indexOf(word) === -1) - fileMap.get(file).push(word); - else fileMap.set(file, [word]); + if (!fileMap.has(file)) fileMap.set(file, [word]); + else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word); }); }); @@ -549,8 +594,8 @@ const Search = { * search summary for a given text. keywords is a list * of stemmed words. */ - makeSearchSummary: (htmlText, keywords) => { - const text = Search.htmlToText(htmlText); + makeSearchSummary: (htmlText, keywords, anchor) => { + const text = Search.htmlToText(htmlText, anchor); if (text === "") return null; const textLower = text.toLowerCase(); diff --git a/asynDriver.html b/asynDriver.html index 38b46ecfd..7240f9c34 100644 --- a/asynDriver.html +++ b/asynDriver.html @@ -16,7 +16,7 @@ - + @@ -192,6 +192,7 @@
  • testApp
  • testArrayRingBufferApp
  • testAsynPortClientApp
    • +
  • testAsynPortDriverApp
  • testBroadcastApp
    • -

  • Install and Build

    +

  • Install and Build

    • -

  • License Agreement

    • +

  • License Agreement

    • @@ -623,7 +625,7 @@

    Acknowledgments< arbitrary low level message based drivers, i.e. GPIB, serial, etc.

    -

  • Jun-ichi Odagare

    +

  • Jun-ichi Odagiri