commit bbd4625d43ad184a492e7f7d267e479acac6f68c Author: Morgan Hughes Date: Tue Jun 28 15:25:57 2022 -0700 Initial commit of Pollcat library diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1d81839 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +*.o +.*.swp +/libpollcat.a +/libpollcat.so* diff --git a/COPYING b/COPYING new file mode 100644 index 0000000..94a9ed0 --- /dev/null +++ b/COPYING @@ -0,0 +1,674 @@ + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. diff --git a/COPYING.LESSER b/COPYING.LESSER new file mode 100644 index 0000000..fc8a5de --- /dev/null +++ b/COPYING.LESSER @@ -0,0 +1,165 @@ + GNU LESSER GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + + This version of the GNU Lesser General Public License incorporates +the terms and conditions of version 3 of the GNU General Public +License, supplemented by the additional permissions listed below. + + 0. Additional Definitions. + + As used herein, "this License" refers to version 3 of the GNU Lesser +General Public License, and the "GNU GPL" refers to version 3 of the GNU +General Public License. + + "The Library" refers to a covered work governed by this License, +other than an Application or a Combined Work as defined below. + + An "Application" is any work that makes use of an interface provided +by the Library, but which is not otherwise based on the Library. +Defining a subclass of a class defined by the Library is deemed a mode +of using an interface provided by the Library. + + A "Combined Work" is a work produced by combining or linking an +Application with the Library. The particular version of the Library +with which the Combined Work was made is also called the "Linked +Version". + + The "Minimal Corresponding Source" for a Combined Work means the +Corresponding Source for the Combined Work, excluding any source code +for portions of the Combined Work that, considered in isolation, are +based on the Application, and not on the Linked Version. + + The "Corresponding Application Code" for a Combined Work means the +object code and/or source code for the Application, including any data +and utility programs needed for reproducing the Combined Work from the +Application, but excluding the System Libraries of the Combined Work. + + 1. Exception to Section 3 of the GNU GPL. + + You may convey a covered work under sections 3 and 4 of this License +without being bound by section 3 of the GNU GPL. + + 2. Conveying Modified Versions. + + If you modify a copy of the Library, and, in your modifications, a +facility refers to a function or data to be supplied by an Application +that uses the facility (other than as an argument passed when the +facility is invoked), then you may convey a copy of the modified +version: + + a) under this License, provided that you make a good faith effort to + ensure that, in the event an Application does not supply the + function or data, the facility still operates, and performs + whatever part of its purpose remains meaningful, or + + b) under the GNU GPL, with none of the additional permissions of + this License applicable to that copy. + + 3. Object Code Incorporating Material from Library Header Files. + + The object code form of an Application may incorporate material from +a header file that is part of the Library. You may convey such object +code under terms of your choice, provided that, if the incorporated +material is not limited to numerical parameters, data structure +layouts and accessors, or small macros, inline functions and templates +(ten or fewer lines in length), you do both of the following: + + a) Give prominent notice with each copy of the object code that the + Library is used in it and that the Library and its use are + covered by this License. + + b) Accompany the object code with a copy of the GNU GPL and this license + document. + + 4. Combined Works. + + You may convey a Combined Work under terms of your choice that, +taken together, effectively do not restrict modification of the +portions of the Library contained in the Combined Work and reverse +engineering for debugging such modifications, if you also do each of +the following: + + a) Give prominent notice with each copy of the Combined Work that + the Library is used in it and that the Library and its use are + covered by this License. + + b) Accompany the Combined Work with a copy of the GNU GPL and this license + document. + + c) For a Combined Work that displays copyright notices during + execution, include the copyright notice for the Library among + these notices, as well as a reference directing the user to the + copies of the GNU GPL and this license document. + + d) Do one of the following: + + 0) Convey the Minimal Corresponding Source under the terms of this + License, and the Corresponding Application Code in a form + suitable for, and under terms that permit, the user to + recombine or relink the Application with a modified version of + the Linked Version to produce a modified Combined Work, in the + manner specified by section 6 of the GNU GPL for conveying + Corresponding Source. + + 1) Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (a) uses at run time + a copy of the Library already present on the user's computer + system, and (b) will operate properly with a modified version + of the Library that is interface-compatible with the Linked + Version. + + e) Provide Installation Information, but only if you would otherwise + be required to provide such information under section 6 of the + GNU GPL, and only to the extent that such information is + necessary to install and execute a modified version of the + Combined Work produced by recombining or relinking the + Application with a modified version of the Linked Version. (If + you use option 4d0, the Installation Information must accompany + the Minimal Corresponding Source and Corresponding Application + Code. If you use option 4d1, you must provide the Installation + Information in the manner specified by section 6 of the GNU GPL + for conveying Corresponding Source.) + + 5. Combined Libraries. + + You may place library facilities that are a work based on the +Library side by side in a single library together with other library +facilities that are not Applications and are not covered by this +License, and convey such a combined library under terms of your +choice, if you do both of the following: + + a) Accompany the combined library with a copy of the same work based + on the Library, uncombined with any other library facilities, + conveyed under the terms of this License. + + b) Give prominent notice with the combined library that part of it + is a work based on the Library, and explaining where to find the + accompanying uncombined form of the same work. + + 6. Revised Versions of the GNU Lesser General Public License. + + The Free Software Foundation may publish revised and/or new versions +of the GNU Lesser General Public License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the +Library as you received it specifies that a certain numbered version +of the GNU Lesser General Public License "or any later version" +applies to it, you have the option of following the terms and +conditions either of that published version or of any later version +published by the Free Software Foundation. If the Library as you +received it does not specify a version number of the GNU Lesser +General Public License, you may choose any version of the GNU Lesser +General Public License ever published by the Free Software Foundation. + + If the Library as you received it specifies that a proxy can decide +whether future versions of the GNU Lesser General Public License shall +apply, that proxy's public statement of acceptance of any version is +permanent authorization for you to choose that version for the +Library. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..5dad98f --- /dev/null +++ b/Makefile @@ -0,0 +1,101 @@ +# Top-level Makefile +# +# This file is part of the Pollcat Library. +# Copyright (C) 2022 Expatria Technologies Inc. +# Contact: Morgan Hughes +# +# The Pollcat Library is free software: you can redistribute it and/or modify it under the +# terms of the the GNU Lesser General Public License as published by the Free Software +# Foundation; either version 3 of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, but WITHOUT ANY +# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. See the GNU General Public License for more details. +# +# You should have received copies of the GNU General Public License and the GNU Lesser +# General Public License along with the Pollcat Library. If not, see +# https://www.gnu.org/licenses/ +# +# vim:ts=4:noexpandtab + +# Integrators should override these +PREFIX ?= /usr/local +export PREFIX DESTDIR + +# version numbers +export MAJOR_VERSION := 0 +export MINOR_VERSION := 1 +export PATCH_VERSION := 0 + +# output names +export NAME = pollcat +export LNAME = $(NAME) +export ANAME = lib$(LNAME).a +export LDNAME = lib$(LNAME).so +export SONAME = $(LDNAME).$(MAJOR_VERSION) +export OUTPUT = $(SONAME).$(MINOR_VERSION).$(PATCH_VERSION) + +# Setup CC/CFLAGS/LFLAGS to allow override +CFLAGS += -O2 -Iinclude -Wall -Werror -fpic +LDFLAGS += -shared + +# Debug build +#CFLAGS += -g + +# Release build +CFLAGS += -DNDEBUG +LDFLAGS += -s + + +# Objects list and export script are minimal +OBJS := src/pollcat.o +OBJS += src/timer.o +OBJS += src/struct.o + +SCRIPTS := -Wl,--version-script,src/$(NAME).v + + +# normal build targets +all: $(ANAME) $(LDNAME) $(SONAME) $(OUTPUT) + $(MAKE) -C tests all + +$(ANAME): $(OBJS) + $(AR) rcs $@ $^ + +$(OUTPUT): $(OBJS) + $(CC) $(LDFLAGS) -Wl,-soname,$(SONAME) $(SCRIPTS) -o$(OUTPUT) $(OBJS) $(LIBS) + +$(SONAME): $(OUTPUT) + ln -sf $(OUTPUT) $(SONAME) + +$(LDNAME): $(SONAME) + ln -sf $(SONAME) $(LDNAME) + +%.o: %.c + $(CC) $(CFLAGS) -c $< -o $@ + +# install runtime libs to rootfs, and includes and static libs. +install: all + $(MAKE) rootfs + mkdir -p $(DESTDIR)$(PREFIX)/lib + install -m644 $(ANAME) $(DESTDIR)$(PREFIX)/lib + mkdir -p $(DESTDIR)$(PREFIX)/include + cp -a include/* $(DESTDIR)$(PREFIX)/include + +# install just runtime libs, for embedded rootfs +rootfs: all + mkdir -p $(DESTDIR)$(PREFIX)/lib + install -m755 $(OUTPUT) $(DESTDIR)$(PREFIX)/lib + ln -sf $(OUTPUT) $(DESTDIR)$(PREFIX)/lib/$(SONAME) + ln -sf $(SONAME) $(DESTDIR)$(PREFIX)/lib/$(LDNAME) + +clean: + rm -f $(OBJS) + rm -f $(ANAME) + rm -f $(OUTPUT) + rm -f $(SONAME) + rm -f $(LDNAME) + $(MAKE) -C tests clean + +.PHONY: all install stage clean + diff --git a/README.md b/README.md new file mode 100644 index 0000000..8e246bd --- /dev/null +++ b/README.md @@ -0,0 +1,111 @@ +# Pollcat Library + +Pollcat is a lightweight library which wraps the `poll()` system call and makes it easy to +build nonblocking applications where cooperative scheduling is adequate and threads are +not warranted. + +It provides an API for managing a list of `pollfd` structs, timeouts, and the `poll()` +system call; millisecond-resolution oneshot timers; an embeddable struct to anchor +pollable objects; and iterators and wrappers for a simple main loop. + +Operations which can fail (ie due to memory allocation) return void to simplify user code; +instead a fatal error triggers a callback to a user-supplied handler, or an error message +and call to `abort()`. + +The library is released under LGPL v3. + + +## Poll API + +An internal sorted `pollfd` array is populated with functions which add, modify, and remove +FDs and event bitmasks; the returned events bitmask can be queried. An internal timeout +value is maintained and used inside the `poll()` call wrapper, it can be reduced by other +code to improve latency. + +As with `poll()` timeouts are managed in milliseconds. Pollcat maintains an internal +minimum timeout, used by default by the wrapped `poll()` call. Interfaces using pollcat +for non-blocking plumbing may optionally reduce the current timeout per loop, so the +`poll()` call returns when appropriate. + +This is used by the timer API to ensure the `poll()` returns at the correct idle time so +the pending timer(s) can be serviced. + +* `void pollcat_fd_add()` - Add an FD to the internal `pollfd` array, or change the events + value on an existing entry +* `void pollcat_fd_remove()` - Remove an FD from the internal `pollfd` array +* `short int pollcat_events_get()` - Get the events field for an FD +* `void pollcat_events_set()` - Set the events field for an FD +* `short int pollcat_revents()` - Get the revents field for an FD, after `poll()` +* `pollcat_time_reduce()` - Reduce the current timeout if time is shorter +* `int pollcat_poll()` - Call `poll()` on the internal `pollfd` array and current + timeout +* `extern pollcat_assert_f pollcat_assert_func` - Optional user-supplied function to + handle fatal errors; if unset a message will be printed to stderr and `abort()` called + to terminate the process +* `extern int pollcat_time_base` - The base timeout in milliseconds for `poll()` - the + current timeout is reset to this after each wrapped `poll()` call. The default is set + at compile time with the symbol `POLLCAT_TIME_BASE` +* `extern int pollcat_time_minimum` - The minimum timeout in milliseconds for `poll()` - + the default is set at compile time with the symbol `POLLCAT_TIME_MINIMUM` +* `extern size_t pollcat_size_initial` - The initial size of the internal `pollfd` array. + The default is set at compile time with the symbol `POLLCAT_SIZE_INITIAL` +* `extern size_t pollcat_size_increment` - The incremental size to grow the internal + `pollfd` array by when necessary. The default is set at compile time with the symbol + `POLLCAT_SIZE_INCREMENT` + + +## Event Timers + +A simple oneshot timer is provided for timed events; timers can be detached and +re-attached at any time. If using the convenience functions, the due time for the +`poll()` timeout is automatically reduced to the nearest timer. + +If not using the `pollcat_loop()` function, the user should call the timer reduction +function before `poll()` and the dispatch function after. + +* `void pollcat_timer_attach()` - Attach a timer to the active list, specifying timeout in + milliseconds, callback function, and argument +* `void pollcat_timer_detach()` - Detach a timer from the active list +* `void pollcat_timer_reduce_timeout()` - Calculate the deadline to the next timer due, + and reduce the `poll()` timeout to match, if less than the current timeout +* `void pollcat_timer_dispatch()` - Execute timers which are due +* `extern int pollcat_timer_dispatch_max` - Sets the maximum number of timers executed per + call to `pollcat_timer_dispatch()` +* `extern pollcat_time_t pollcat_timer_dispatch_thresh` - Sets a "grace" time for delayed + timers +* `typedef uint64_t pollcat_time_t` - Sets the timer type, tunable for system size + + +## Embeddable Struct and Convenience API + +Pollcat implements a base struct with linked-list and operations struct pointers. This +can be embedded in other structs to make them easily plugged into a polling main loop. + +The `pollcat_loop()` function will iterate through the list, calling the supplied +`prepare()` function before `poll()` and the supplied `service()` function after. + +Pollcat objects can be added to an internal list with the `pollcat_iter_add()` function, +and the main-loop function `pollcat_loop()` will iterate through them, perform the +`poll()` call, and service timers. + +* `struct pollcat` - Pollcat object structure, passed to the convenience API functions +* `struct pollcat_ops` - Operations structure, with function pointers supplied by the user + or objects which wrap a Pollcat object. +* `void pollcat_iter_add()` - Add a Pollcat object to the iterator list +* `void pollcat_iter_remove()` - Remove a Pollcat object from the iterator list +* `void pollcat_iter_reset()` - Reset the cursor on the iterator list +* `struct pollcat *pollcat_iter_next()` - Return the next Pollcat object on the list +* `int pollcat_loop()` - Service active timers and Pollcat objects; returns true as long + as main loop should continue +* `void pollcat_loop_exit()` - Sets a flag so `pollcat_loop()` will return false and main + loop will stop + + +## Example Application + +An example application is provided which demonstrates use of the library. It provides a +simple terminal to a serial device, with a command mode triggered by Ctrl-A. A timer +shows a menu after 1 second. The only command implemented is to shut down, via the Q or X +keys, with or without Ctrl. + + diff --git a/example/.gitignore b/example/.gitignore new file mode 100644 index 0000000..5b3fa46 --- /dev/null +++ b/example/.gitignore @@ -0,0 +1 @@ +/terminal diff --git a/example/Makefile b/example/Makefile new file mode 100644 index 0000000..aa7d355 --- /dev/null +++ b/example/Makefile @@ -0,0 +1,43 @@ +# Example Makefile +# +# This file is part of the Pollcat Library. +# Copyright (C) 2022 Expatria Technologies Inc. +# Contact: Morgan Hughes +# +# The Pollcat Library is free software: you can redistribute it and/or modify it under the +# terms of the the GNU Lesser General Public License as published by the Free Software +# Foundation; either version 3 of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, but WITHOUT ANY +# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. See the GNU General Public License for more details. +# +# You should have received copies of the GNU General Public License and the GNU Lesser +# General Public License along with the Pollcat Library. If not, see +# https://www.gnu.org/licenses/ +# +# vim:ts=4:noexpandtab + +TERM_OBJS := tty.o main.o serial.o command.o +TERM_LIBS := -lpollcat + +.PHONY: all install clean + +all: terminal + +terminal: $(TERM_OBJS) + $(CC) $(CFLAGS) $(LFLAGS) $^ $(TERM_LIBS) -o $@ + +install: + false + +clean: + rm -f $(TERM_OBJS) + rm -f terminal + +%.i: %.c + $(CC) $(CFLAGS) -E $< -o $@ + +%.o: %.c + $(CC) $(CFLAGS) -c $< -o $@ + diff --git a/example/command.c b/example/command.c new file mode 100644 index 0000000..c1c8901 --- /dev/null +++ b/example/command.c @@ -0,0 +1,67 @@ +/* Library exports + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#include +#include +#include +#include +#include +#include +#include + +#include + +#include "terminal.h" + + +char command_char = '\01'; +int command_mode = 0; + +void command_help (void) +{ + fprintf(stderr, + "\r\nMenu\r\n" + "Q - Quit\r\n" + "X - Exit\r\n" + "\r\n"); +} + +void command_recv (char c) +{ + switch ( tolower(c) ) + { + case 'q': + case 'x': + case '\x11': + case '\x18': + pollcat_loop_exit(); + return; + + case '\01': + serial_write(&c, sizeof(c)); + return; + + default: + command_help(); + return; + } +} + diff --git a/example/main.c b/example/main.c new file mode 100644 index 0000000..35bd113 --- /dev/null +++ b/example/main.c @@ -0,0 +1,98 @@ +/** Minimal terminal using pollcat - main loop + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#include +#include +#include +#include +#include + +#include + +#include "terminal.h" + + +char *opt_node = "/dev/ttyUSB0"; +char *opt_speed = "115200N81"; + + +static void signal_fatal (int signum) +{ + fprintf(stderr, "Fatal signal %d, exit loop\n", signum); + pollcat_loop_exit(); +} + +extern char *__progname; +static void usage (void) +{ + printf("Usage: %s [-t timeout] [-b speed] [node]\n" + "-t timeout Timeout for poll() calls (ms)\n" + "-b speed Speed/parity/data/stop bits (default 115200N81)\n" + "node should be a serial device, such as /dev/ttyS0 or /dev/ttyUSB0\n", + __progname); + exit(1); +} + +int main (int argc, char **argv) +{ + int opt; + while ( (opt = getopt(argc, argv, "t:b:")) != -1 ) + switch ( opt ) + { + case 't': + pollcat_time_base = atoi(optarg); + break; + + case 'b': + opt_speed = optarg; + break; + + default: + usage(); + } + + if ( optind < argc ) + opt_node = argv[optind]; + + if ( serial_init(opt_node, opt_speed) ) + { + perror(opt_node); + return 1; + } + + if ( tty_init() ) + { + perror("tty_init"); + return 1; + } + + signal(SIGTERM, signal_fatal); + signal(SIGINT, signal_fatal); + + while ( pollcat_loop(NULL) ) + ; + + tty_done(); + serial_done(); + + return 0; +} + diff --git a/example/serial.c b/example/serial.c new file mode 100644 index 0000000..e2f8e3d --- /dev/null +++ b/example/serial.c @@ -0,0 +1,244 @@ +/** minimal terminal using pollcat + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#include +#include +#include +#include +#include +#include + +#include + +#include "terminal.h" + + +static int fd; + + +static void service (struct pollcat *cat) +{ + char buff[4096]; + int ret; + int idx; + + if ( !(pollcat_revents(fd) & POLLIN) ) + return; + + while ( (ret = read(fd, buff, sizeof(buff))) > 0 ) + tty_write(buff, ret); +} + +static const struct pollcat_ops ops = +{ + .service = service, +}; + +static struct pollcat cat = +{ + .ops = &ops, +}; + +static int serial_fl; +static int serial_fd; +static struct termios serial_tio; + +int serial_init (const char *node, const char *setup) +{ + speed_t spd; + char *mod; + + if ( (fd = open(node, O_RDWR, 0)) < 0 ) + return -1; + + // set stdin nonblocking + if ( (serial_fl = fcntl(fd, F_GETFL)) < 0 ) + return -1; + if ( fcntl(fd, F_SETFL, serial_fl | O_NONBLOCK) < 0 ) + return -1; + + // set stdin nonblocking + if ( (serial_fd = fcntl(fd, F_GETFD)) < 0 ) + return -1; + if ( fcntl(fd, F_SETFD, serial_fd | FD_CLOEXEC) < 0 ) + return -1; + + // save old terminal modes and make raw + if ( tcgetattr(fd, &serial_tio) ) + return -1; + + struct termios tio = serial_tio; + cfmakeraw(&tio); + + switch ( strtoul(setup, &mod, 10) ) + { + case 50: spd = B50; break; + case 75: spd = B75; break; + case 110: spd = B110; break; + case 134: spd = B134; break; + case 150: spd = B150; break; + case 200: spd = B200; break; + case 300: spd = B300; break; + case 600: spd = B600; break; + case 1200: spd = B1200; break; + case 1800: spd = B1800; break; + case 2400: spd = B2400; break; + case 4800: spd = B4800; break; + case 9600: spd = B9600; break; + case 19200: spd = B19200; break; + case 38400: spd = B38400; break; + case 57600: spd = B57600; break; + case 115200: spd = B115200; break; +#ifdef B230400 + case 230400: spd = B230400; break; +#endif +#ifdef B460800 + case 460800: spd = B460800; break; +#endif +#ifdef B500000 + case 500000: spd = B500000; break; +#endif +#ifdef B576000 + case 576000: spd = B576000; break; +#endif +#ifdef B921600 + case 921600: spd = B921600; break; +#endif +#ifdef B1000000 + case 1000000: spd = B1000000; break; +#endif +#ifdef B1152000 + case 1152000: spd = B1152000; break; +#endif +#ifdef B1500000 + case 1500000: spd = B1500000; break; +#endif +#ifdef B2000000 + case 2000000: spd = B2000000; break; +#endif +#ifdef B2500000 + case 2500000: spd = B2500000; break; +#endif +#ifdef B3000000 + case 3000000: spd = B3000000; break; +#endif +#ifdef B3500000 + case 3500000: spd = B3500000; break; +#endif +#ifdef B4000000 + case 4000000: spd = B4000000; break; +#endif + default: + errno = EINVAL; + return -1; + } + if ( cfsetispeed(&tio, spd) || cfsetospeed(&tio, spd) ) + return -1; + + while ( *mod ) + { + switch ( toupper(*mod) ) + { + // data bits + case '8': tio.c_cflag &= ~CSIZE; tio.c_cflag |= CS8; break; + case '7': tio.c_cflag &= ~CSIZE; tio.c_cflag |= CS7; break; + case '6': tio.c_cflag &= ~CSIZE; tio.c_cflag |= CS6; break; + case '5': tio.c_cflag &= ~CSIZE; tio.c_cflag |= CS5; break; + + // stop bits + case '2': tio.c_cflag |= CSTOPB; break; + case '1': tio.c_cflag &= ~CSTOPB; break; + + // no parity + case 'N': + tio.c_iflag |= IGNPAR; + tio.c_iflag &= ~INPCK; + tio.c_cflag &= ~(PARENB | PARODD | CMSPAR); + break; + + // odd parity + case 'O': + tio.c_iflag |= INPCK | PARMRK; + tio.c_iflag &= ~IGNPAR; + tio.c_cflag |= PARENB | PARODD; + tio.c_cflag &= ~CMSPAR; + break; + + // even parity + case 'E': + tio.c_iflag |= INPCK | PARMRK; + tio.c_iflag &= ~IGNPAR; + tio.c_cflag |= PARENB; + tio.c_cflag &= ~(PARODD | CMSPAR); + break; + + // mark parity + case 'M': + tio.c_iflag |= INPCK | PARMRK; + tio.c_iflag &= ~IGNPAR; + tio.c_cflag |= PARENB | CMSPAR | PARODD; + break; + + // space parity + case 'S': + tio.c_iflag |= INPCK | PARMRK; + tio.c_iflag &= ~IGNPAR; + tio.c_cflag |= PARENB | CMSPAR; + tio.c_cflag &= ~PARODD; + break; + + default: + errno = EINVAL; + return -1; + } + mod++; + } + + if ( tcsetattr(fd, TCSANOW, &tio) ) + return -1; + + pollcat_fd_add(fd, POLLIN); + pollcat_iter_add(&cat); + return 0; +} + + +void serial_done (void) +{ + pollcat_iter_remove(&cat); + pollcat_fd_remove(fd); + + if ( fcntl(fd, F_SETFL, serial_fl) < 0 ) + perror("fcntl"); + + if ( fcntl(fd, F_SETFD, serial_fd) < 0 ) + perror("fcntl"); + + if ( tcsetattr(fd, TCSANOW, &serial_tio) ) + perror("tcsetattr"); + + close(fd); +} + +void serial_write (const void *buff, int len) +{ + write(fd, buff, len); +} diff --git a/example/terminal.h b/example/terminal.h new file mode 100644 index 0000000..acfe82d --- /dev/null +++ b/example/terminal.h @@ -0,0 +1,41 @@ +/** Minimal terminal using pollcat - prototypes + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#ifndef _INCLUDE_TERMINAL_H_ +#define _INCLUDE_TERMINAL_H_ + +/* command.c */ +extern char command_char; +extern int command_mode; +void command_help (void); +void command_recv (char c); + +/* serial.c */ +int serial_init (const char *node, const char *speed); +void serial_done (void); +void serial_write (const void *buf, int len); + +/* tty.c */ +int tty_init (void); +void tty_done (void); +void tty_write (const void *buf, int len); + +#endif /* _INCLUDE_TERMINAL_H_ */ diff --git a/example/tty.c b/example/tty.c new file mode 100644 index 0000000..469a555 --- /dev/null +++ b/example/tty.c @@ -0,0 +1,151 @@ +/** Minimal terminal using pollcat - TTY side + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#include +#include +#include +#include +#include +#include +#include + +#include + +#include "terminal.h" + + +static struct pollcat_timer timer = { 0 }; +static void callback (void *arg) +{ + command_help(); +} + + +static void service (struct pollcat *cat) +{ + char buff[256]; + char *ptr; + int ret; + + if ( !(pollcat_revents(fileno(stdin)) & POLLIN) ) + return; + + memset(buff, 0, sizeof(buff)); + if ( (ret = read(fileno(stdin), buff, sizeof(buff) - 1)) < 0 ) + { + fprintf(stderr, "recv(%d): %s", ret, strerror(errno)); + pollcat_loop_exit(); + return; + } + + if ( command_mode ) + { + pollcat_timer_detach(&timer); + command_recv(buff[0]); + command_mode = 0; + return; + } + + if ( !(ptr = memchr(buff, command_char, ret)) ) + { + serial_write(buff, ret); + return; + } + + if ( ptr > buff ) + serial_write(buff, ptr - buff); + + if ( (1 + ptr - buff) < ret ) + { + pollcat_timer_detach(&timer); + command_recv(ptr[1]); + } + else + { + pollcat_timer_attach(&timer, 1000, callback, NULL); + command_mode = 1; + } +} + +static const struct pollcat_ops ops = +{ + .service = service, +}; + +struct pollcat cat = +{ + .ops = &ops, +}; + +static int tty_flags; +static struct termios tty_tio; + +int tty_init (void) +{ + char tty[256]; + memset(tty, 0, sizeof(tty)); + if ( readlink("/proc/self/fd/1", tty, sizeof(tty)) > 0 ) + { + if ( !freopen(tty, "w", stdout) || !freopen(tty, "w", stderr) ) + perror(tty); + setbuf(stderr, NULL); + } + + tty_flags = fcntl(fileno(stdin), F_GETFL); + if ( tty_flags < 0 ) + return -1; + + if ( fcntl(fileno(stdin), F_SETFL, tty_flags | O_NONBLOCK) < 0 ) + return -1; + + if ( tcgetattr(fileno(stdin), &tty_tio) ) + return -1; + + struct termios tio = tty_tio; + cfmakeraw(&tio); + if ( tcsetattr(fileno(stdin), TCSANOW, &tio) ) + return -1; + + pollcat_fd_add(fileno(stdin), POLLIN); + pollcat_iter_add(&cat); + + command_char = '\01'; + command_mode = 0; + return 0; +} + +void tty_done (void) +{ + pollcat_iter_remove(&cat); + pollcat_fd_remove(fileno(stdin)); + + if ( fcntl(0, F_SETFL, tty_flags) < 0 ) + perror("fcntl"); + + if ( tcsetattr(0, TCSANOW, &tty_tio) ) + perror("tcsetattr"); +} + +void tty_write (const void *buff, int len) +{ + write(fileno(stdout), buff, len); +} + diff --git a/include/pollcat.h b/include/pollcat.h new file mode 100644 index 0000000..f6b68a8 --- /dev/null +++ b/include/pollcat.h @@ -0,0 +1,31 @@ +/** Pollcat library include wrapper + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#ifndef _INCLUDE_POLLCAT_H_ +#define _INCLUDE_POLLCAT_H_ + + +#include "pollcat/pollcat.h" +#include "pollcat/timer.h" +#include "pollcat/struct.h" + + +#endif /* _INCLUDE_POLLCAT_H_ */ diff --git a/include/pollcat/pollcat.h b/include/pollcat/pollcat.h new file mode 100644 index 0000000..5ab111e --- /dev/null +++ b/include/pollcat/pollcat.h @@ -0,0 +1,133 @@ +/** Wrapper structure for poll() + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#ifndef _INCLUDE_POLLCAT_POLLCAT_H_ +#define _INCLUDE_POLLCAT_POLLCAT_H_ + +#ifndef POLLCAT_TIME_BASE +#define POLLCAT_TIME_BASE 250 +#endif +#ifndef POLLCAT_TIME_MINIMUM +#define POLLCAT_TIME_MINIMUM 5 +#endif +#ifndef POLLCAT_SIZE_INITIAL +#define POLLCAT_SIZE_INITIAL 8 +#endif +#ifndef POLLCAT_SIZE_INCREMENT +#define POLLCAT_SIZE_INCREMENT 8 +#endif +#ifndef POLLCAT_DEBUG +#define POLLCAT_DEBUG 1 +#endif + +#include +#include +#if POLLCAT_DEBUG +#include +#endif + + +/** Optional function to call on fatal error; if unset an assert()-style message will be + * printed on stderr and exit(1) called. + */ +typedef void (* pollcat_assert_f) (const char *file, int line, const char *mesg); +extern pollcat_assert_f pollcat_assert_func; + + +/** Base timeout for wrapped poll() calls in milliseconds; pollcat_time_reduce() may be + * called to reduce this on a per-loop basis to improve latency of things like timers. + * The default is POLLCAT_TIME_BASE. + */ +extern int pollcat_time_base; + +/** Minimum timeout for wrapped poll() calls in milliseconds; pollcat_time_reduce() will + * not reduce the per-loop timeout below this value. The default is POLLCAT_TIME_MINIMUM. + */ +extern int pollcat_time_minimum; + +/** Initial size of the pollfd array. The default is POLLCAT_SIZE_INITIAL. + */ +extern size_t pollcat_size_initial; + +/** Incremental size of the pollfd array. The default is POLLCAT_SIZE_INCREMENT. + */ +extern size_t pollcat_size_increment; + + +/** Add an FD to the poll array and set the events requested + * + * \param fd File descriptor + * \param events Bitmap of events from poll.h, such as POLLIN + */ +void pollcat_fd_add (int fd, short int events); + +/** Get request bits of an FD in the poll array + * + * \param fd File descriptor + * + * \return bitmap on success, <0 on error + */ +short int pollcat_events_get (int fd); + +/** Set request bits on an FD in the poll array + * + * \param fd File descriptor + * \param events Bitmap of events from poll.h, such as POLLIN + */ +void pollcat_events_set (int fd, short int events); + +/** Get result bits of an FD in the poll array + * + * \param fd File descriptor + * + * \return bitmap on success, 0 on error + */ +short int pollcat_revents (int fd); + +/** Remove an FD from the poll array + * + * \param fd File descriptor + */ +void pollcat_fd_remove (int fd); + + +/** Reduce the current timeout + * + * \param time New timeout in milliseconds + */ +void pollcat_time_reduce (int time); + + +/** Wraps the system poll() command using the internal pollfd array and timeout + * + * \return as per poll(), <0 on error + */ +int pollcat_poll (void); + + +#if POLLCAT_DEBUG +/** Prints the pollfd array to a given file handle + */ +void pollcat_dump (FILE *fp); +#endif + + +#endif /* _INCLUDE_POLLCAT_POLLCAT_H_ */ diff --git a/include/pollcat/struct.h b/include/pollcat/struct.h new file mode 100644 index 0000000..38e044e --- /dev/null +++ b/include/pollcat/struct.h @@ -0,0 +1,103 @@ +/** Registration struct, iterators, and main-loop convenience functions + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#ifndef _INCLUDE_POLLCAT_STRUCT_H_ +#define _INCLUDE_POLLCAT_STRUCT_H_ +#include + + +struct pollcat_ops; + +/** Pollcat object structure */ +struct pollcat +{ + void *data; + const struct pollcat_ops *ops; + struct pollcat *next; +}; + + +/** Timer callbacks type takes a single void pointer */ +typedef void (* pollcat_service_f)(struct pollcat *); + + +/** Operations structure for a pollcat object */ +struct pollcat_ops +{ + /* Prepare function is called before poll(); it's a good place to do things like + * accept() incoming connections, or add new file descriptors. */ + pollcat_service_f prepare; + + /* Service function is called after poll(); it's the place to check revents for FDs + * and do the appropriate read/write options. */ + pollcat_service_f service; +}; + + +/** Add a pollcat object to the internal iterator list + * + * \param cat Pointer to pollcat object + */ +void pollcat_iter_add (struct pollcat *cat); + + +/** Remove pollcat object from the internal iterator list + * + * \param cat Pointer to pollcat object + */ +void pollcat_iter_remove (struct pollcat *cat); + + +/** Reset cursor for internal iterator list + */ +void pollcat_iter_reset (void); + +/** Return next pollcat object in internal iterator list + * + * \return Pointer to next pollcat object in list, or NULL at end of list + */ +struct pollcat *pollcat_iter_next (void); + + +/** Loop wrapper function + * + * This should be called as the test in a while() loop in main. Internally it will: + * - check whether pollcat_loop_exit() has been called, and return 0 if so + * - call pollcat_timer_reduce_timeout() to improve timer latency + * - call ops.prepare() on each pollcat object in the internal iterator list + * - call pollcat_poll() and optionally save the return value in poll-ret + * - call pollcat_timer_dispatch() to dispatch any expired timers + * - call ops.service() on each pollcat object in the internal iterator list + * - return nonzero for next loop + * + * \param poll_ret Optional pointer to int for return value from poll() call + * + * \return nonzero if main loop should continue, 0 if it should break + */ +int pollcat_loop (int *poll_ret); + + +/** Cause pollcat_loop() to return 0 on its next call + */ +void pollcat_loop_exit (void); + + +#endif /* _INCLUDE_POLLCAT_STRUCT_H_ */ diff --git a/include/pollcat/timer.h b/include/pollcat/timer.h new file mode 100644 index 0000000..fcf3589 --- /dev/null +++ b/include/pollcat/timer.h @@ -0,0 +1,95 @@ +/** Millisecond-resolution event timers + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#ifndef _INCLUDE_POLLCAT_TIMER_H_ +#define _INCLUDE_POLLCAT_TIMER_H_ +#include + + +/** Clocks type adjustable in size, units milliseconds for compatibility with poll() */ +typedef uint64_t pollcat_time_t; + + +/** Grace period in milliseconds for late timers, set to 0 for exact match */ +extern pollcat_time_t pollcat_timer_dispatch_thresh; + + +/** Maximum number of times to run the dispatch loop, set to -1 for no limit */ +extern int pollcat_timer_dispatch_max; + + +/** Timer callbacks type takes a single void pointer */ +typedef void (* pollcat_timer_f)(void *); + + +/** Timer struct; zero-fill to init */ +struct pollcat_timer +{ + pollcat_timer_f func; + pollcat_time_t due; + void *arg; + + struct pollcat_timer *next; + struct pollcat_timer *prev; +}; + + +/** Detach a timer from the active list + * + * \param timer Pointer to timer struct + */ +void pollcat_timer_detach (struct pollcat_timer *timer); + +/** Attach or re-attach a timer to the active list + * + * \param timer Pointer to timer struct + * \param msec Delay in milliseconds + * \param func Callback function + * \param arg Argument to callback function + */ +void pollcat_timer_attach (struct pollcat_timer *timer, + pollcat_time_t msec, + pollcat_timer_f func, + void *arg); + +/** Returns nonzero if timer is attached + * + * \param timer Pointer to timer struct + * + * \return >0 if timer is attached + */ +int pollcat_timer_is_attached (struct pollcat_timer *timer); + + +/** Reduce the poll() timeout + * + * This should be called each main loop before the pollcat_poll() call, so that a ready + * timer isn't delayed. + */ +void pollcat_timer_reduce_timeout (void); + + +/** Dispatch ready timers + */ +void pollcat_timer_dispatch (void); + + +#endif /* _INCLUDE_POLLCAT_TIMER_H_ */ diff --git a/src/pollcat.c b/src/pollcat.c new file mode 100644 index 0000000..cb4fdf0 --- /dev/null +++ b/src/pollcat.c @@ -0,0 +1,370 @@ +/** Wrapper structure for poll() + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#include +#include +#include +#include +#include +#include +#include + +#include +#include "private.h" + + +static struct pollfd *pollcat_list = NULL; +static size_t pollcat_size = 0; +static size_t pollcat_used = 0; +static int pollcat_last = -1; + + +static int pollcat_time_current = -1; + +/** Optional function to call on fatal error; if unset an assert()-style message will be + * printed on stderr and abort() called. + */ +typedef void (* pollcat_assert_f) (const char *file, int line, const char *mesg); +pollcat_assert_f pollcat_assert_func = NULL; + +/** Base timeout for wrapped poll() calls in milliseconds; pollcat_time_reduce() may be + * called to reduce this on a per-loop basis to improve latency of things like timers. + * The default is POLLCAT_TIME_BASE. + */ +int pollcat_time_base = POLLCAT_TIME_BASE; + +/** Minimum timeout for wrapped poll() calls in milliseconds; pollcat_time_reduce() will + * not reduce the per-loop timeout below this value. The default is POLLCAT_TIME_MINIMUM. + */ +int pollcat_time_minimum = POLLCAT_TIME_MINIMUM; + +/** Initial size of the pollfd array. The default is POLLCAT_SIZE_INITIAL. + */ +size_t pollcat_size_initial = POLLCAT_SIZE_INITIAL; + +/** Incremental size of the pollfd array. The default is POLLCAT_SIZE_INCREMENT. + */ +size_t pollcat_size_increment = POLLCAT_SIZE_INCREMENT; + + +/** Cleanup function and atexit flag */ +static int pollcat_exit = 0; +static void pollcat_done (void) +{ + free(pollcat_list); + pollcat_list = NULL; + pollcat_size = 0; + pollcat_used = 0; + pollcat_last = -1; +} + +/** Init function */ +static void pollcat_init (void) +{ + /* Register cleanup */ + if ( !pollcat_exit ) + { + atexit(pollcat_done); + pollcat_exit = 1; + } + + if ( pollcat_list ) + return; + + if ( pollcat_size_initial < 1 ) + pollcat_size_initial = 1; + if ( pollcat_size_increment < 1 ) + pollcat_size_increment = 1; + + pollcat_list = malloc(pollcat_size_initial * sizeof(struct pollfd)); + memset(pollcat_list, 0xFF, pollcat_size_initial * sizeof(struct pollfd)); + POLLCAT_ASSERT(pollcat_list != NULL); + + pollcat_size = pollcat_size_initial; + pollcat_used = 0; + pollcat_last = -1; + + pollcat_time_current = pollcat_time_base; +} + +/** Binary search compare function */ +static int pollcat_comp (const void *va, const void *vb) +{ + const struct pollfd *pa = (const struct pollfd *)va; + const struct pollfd *pb = (const struct pollfd *)vb; + + POLLCAT_ASSERT(va != NULL); + POLLCAT_ASSERT(vb != NULL); + + return pa->fd - pb->fd; +} + +/** Binary search function */ +static struct pollfd *pollcat_search (int fd) +{ + struct pollfd key = { 0 }; + struct pollfd *ret; + + if ( pollcat_used < 1 ) + return NULL; + + /* Check cached index first */ + if ( pollcat_last > -1 && pollcat_last < pollcat_used + && pollcat_list[pollcat_last].fd == fd ) + return &pollcat_list[pollcat_last]; + + /* Do binary search and cache result */ + key.fd = fd; + ret = bsearch(&key, pollcat_list, sizeof(struct pollfd), pollcat_used, pollcat_comp); + pollcat_last = ret ? ret - pollcat_list : -1; + return ret; +} + + +/** Add an FD to the poll array and set the events requested + * + * \param fd File descriptor + * \param events Bitmap of events from poll.h, such as POLLIN + */ +void pollcat_fd_add (int fd, short int events) +{ + struct pollfd *pfd; + + /* Auto init, no-return if failed */ + pollcat_init(); + + /* Update existing if found */ + if ( (pfd = pollcat_search(fd)) ) + { + pfd->events = events; + return; + } + + /* Grow list if full */ + if ( pollcat_used == pollcat_size ) + { + size_t new = pollcat_size + pollcat_size_increment; + pfd = malloc(new * sizeof(struct pollfd)); + POLLCAT_ASSERT(pfd != NULL); + + memcpy(pfd, pollcat_list, pollcat_size * sizeof(struct pollfd)); + memset(pfd + pollcat_size, 0xFF, pollcat_size_increment * sizeof(struct pollfd)); + free(pollcat_list); + pollcat_list = pfd; + pollcat_size += pollcat_size_increment; + } + + /* Add new entry and increment used */ + pollcat_list[pollcat_used].fd = fd; + pollcat_list[pollcat_used].events = events; + pollcat_used++; + + /* Re-sort list */ + qsort(pollcat_list, pollcat_used, sizeof(struct pollfd), pollcat_comp); +} + + +/** Get request bits of an FD in the poll array + * + * \param fd File descriptor + * + * \return bitmap on success, <0 if not found + */ +short int pollcat_events_get (int fd) +{ + struct pollfd *pfd; + + /* Auto init, no-return if failed */ + pollcat_init(); + + if ( !(pfd = pollcat_search(fd)) ) + return -1; + + return pfd->events; +} + + +/** Set request bits on an FD in the poll array + * + * \param fd File descriptor + * \param events Bitmap of events from poll.h, such as POLLIN + */ +void pollcat_events_set (int fd, short int events) +{ + struct pollfd *pfd; + + /* Auto init, no-return if failed */ + pollcat_init(); + + if ( !(pfd = pollcat_search(fd)) ) + return; + + pfd->events = events; +} + + +/** Get result bits of an FD in the poll array + * + * \param fd File descriptor + * + * \return bitmap on success, 0 on error + */ +short int pollcat_revents (int fd) +{ + struct pollfd *pfd; + + /* Auto init, no-return if failed */ + pollcat_init(); + + if ( !(pfd = pollcat_search(fd)) ) + return 0; + + return pfd->revents; +} + + +/** Remove an FD from the poll array + * + * \param fd File descriptor + */ +void pollcat_fd_remove (int fd) +{ + struct pollfd *pfd; + + /* Auto init, no-return if failed */ + pollcat_init(); + + if ( !(pfd = pollcat_search(fd)) ) + return; + + /* Last entry in list is cheap */ + if ( 1 == pollcat_used ) + { + pollcat_used--; + pollcat_last = -1; + return; + } + + /* Decrement used and move last entry into vacant slot */ + pollcat_used--; + pfd->fd = pollcat_list[pollcat_used].fd; + pfd->events = pollcat_list[pollcat_used].events; + memset(&pollcat_list[pollcat_used], 0xFF, sizeof(struct pollfd)); + + /* Re-sort list */ + qsort(pollcat_list, pollcat_used, sizeof(struct pollfd), pollcat_comp); +} + + +/** Reduce the current timeout + * + * \param time New timeout in milliseconds + */ +void pollcat_time_reduce (int time) +{ + if ( time < pollcat_time_current ) + pollcat_time_current = time; +} + + +/** Wraps the system poll() command using the internal pollfd array and timeout + * + * \return as per poll(), <0 on error + */ +int pollcat_poll (void) +{ + int ret; + + /* Auto init, no-return if failed */ + pollcat_init(); + + if ( pollcat_time_current < pollcat_time_minimum ) + pollcat_time_current = pollcat_time_minimum; + + ret = poll(pollcat_list, pollcat_used, pollcat_time_current); + pollcat_time_current = pollcat_time_base; + + return ret; +} + +#if POLLCAT_DEBUG +static const char *pollcat_bits (short int events) +{ + static char buff[20] = { 0 }; + char *ins = buff; + + *ins++ = events & POLLIN ? 'I' : '_'; + *ins++ = events & POLLPRI ? 'P' : '_'; + *ins++ = events & POLLOUT ? 'O' : '_'; +#ifdef POLLRDHUP + *ins++ = events & POLLRDHUP ? 'R' : '_'; +#endif + *ins++ = events & POLLERR ? 'E' : '_'; + *ins++ = events & POLLHUP ? 'H' : '_'; + *ins++ = events & POLLNVAL ? 'N' : '_'; +#ifdef POLLMSG + *ins++ = events & POLLMSG ? 'M' : '_'; +#endif +#ifdef _XOPEN_SOURCE + *ins++ = ','; + *ins++ = 'R'; + *ins++ = events & POLLRDNORM ? 'N' : '_'; + *ins++ = events & POLLRDBAND ? 'B' : '_'; + *ins++ = ','; + *ins++ = 'W'; + *ins++ = events & POLLWRNORM ? 'N' : '_'; + *ins++ = events & POLLWRBAND ? 'B' : '_'; +#endif + + return buff; +} + +void pollcat_dump (FILE *fp) +{ + int i; + + if ( !fp && stderr ) + fp = stderr; + if ( !fp && stdout ) + fp = stdout; + + fprintf(fp, "pollcat: list %p, used %zu / size %zu\n", + pollcat_list, pollcat_used, pollcat_size); + + fprintf(fp, "fd events revents path\n"); + for ( i = 0; i < pollcat_used; i++ ) + { + char path[256]; + char link[256]; + + snprintf(path, sizeof(path), "/proc/self/fd/%d", pollcat_list[i].fd); + memset(link, 0, sizeof(link)); + if ( readlink(path, link, sizeof(link) - 1) < 0 ) + snprintf(link, sizeof(link), "err:%s", strerror(errno)); + + fprintf(fp, "%2d %-8s ", pollcat_list[i].fd, + pollcat_bits(pollcat_list[i].events)); + + fprintf(fp, "%-8s %s\n", pollcat_bits(pollcat_list[i].revents), link); + } +} +#endif + diff --git a/src/pollcat.v b/src/pollcat.v new file mode 100644 index 0000000..8aa38d2 --- /dev/null +++ b/src/pollcat.v @@ -0,0 +1,55 @@ +/* Library exports + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +pollcat_0.1 { + global: + /* src/pollcat.c */ + pollcat_assert_func; + pollcat_time_base; + pollcat_time_minimum; + pollcat_size_initial; + pollcat_size_increment; + pollcat_fd_add; + pollcat_events_get; + pollcat_events_set; + pollcat_revents; + pollcat_fd_remove; + pollcat_time_reduce; + pollcat_poll; + pollcat_dump; + /* src/timer.c */ + pollcat_timer_dispatch_max; + pollcat_timer_dispatch_thresh; + pollcat_timer_detach; + pollcat_timer_attach; + pollcat_timer_is_attached; + pollcat_timer_reduce_timeout; + pollcat_timer_dispatch; + /* src/struct.c */ + pollcat_iter_add; + pollcat_iter_remove; + pollcat_iter_reset; + pollcat_iter_next; + pollcat_loop; + pollcat_loop_exit; + local: + *; +}; diff --git a/src/private.h b/src/private.h new file mode 100644 index 0000000..9315052 --- /dev/null +++ b/src/private.h @@ -0,0 +1,43 @@ +/** Private includes + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#ifndef _SRC_PRIVATE_H_ +#define _SRC_PRIVATE_H_ +#include + + +/** Local assert macro */ +#define POLLCAT_ASSERT(test) \ + do { \ + if ( !(test) ) { \ + if ( pollcat_assert_func ) \ + pollcat_assert_func(__FILE__, __LINE__, #test); \ + else if ( stderr ) \ + fprintf(stderr, "%s[%d]: assertion failed: %s (%s)\n", \ + __FILE__, __LINE__, #test, strerror(errno)); \ + abort(); \ + } \ + } while(0) + +extern pollcat_assert_f pollcat_assert_func; + + +#endif /* _SRC_PRIVATE_H_ */ diff --git a/src/struct.c b/src/struct.c new file mode 100644 index 0000000..0008e11 --- /dev/null +++ b/src/struct.c @@ -0,0 +1,169 @@ +/** Registration struct, iterators, and main-loop convenience functions + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#include +#include + +#include +#include "private.h" + + +/* Internal iterator list head and walk */ +static struct pollcat *pollcat_iter_head = NULL; +static struct pollcat *pollcat_iter_curs = NULL; + +/* Loop stop flag */ +static int pollcat_loop_stop = 0; + + +/** Add a pollcat object to the internal iterator list + * + * \param cat Pointer to object + */ +void pollcat_iter_add (struct pollcat *cat) +{ + struct pollcat *walk; + + if ( !pollcat_iter_head ) + { + pollcat_iter_head = cat; + pollcat_iter_curs = NULL; + return; + } + + for ( walk = pollcat_iter_head; walk->next; walk = walk->next ) + ; + + walk->next = cat; + pollcat_iter_curs = pollcat_iter_head; +} + + +/** Remove pollcat object from the internal iterator list + * + * \param cat Pointer to object + */ +void pollcat_iter_remove (struct pollcat *cat) +{ + struct pollcat *walk; + + // empty list: no action needed + if ( !pollcat_iter_head ) + return; + + // object at head: just move the head to the next + if ( cat == pollcat_iter_head ) + { + pollcat_iter_head = pollcat_iter_head->next; + pollcat_iter_curs = pollcat_iter_head; + return; + } + + for ( walk = pollcat_iter_head; walk->next; walk = walk->next ) + if ( walk->next == cat ) + { + walk->next = cat->next; + pollcat_iter_curs = pollcat_iter_head; + return; + } +} + + +/** Reset cursor for internal iterator list + */ +void pollcat_iter_reset (void) +{ + pollcat_iter_curs = pollcat_iter_head; +} + + +/** Return next pollcat object in internal iterator list + * + * \return Pointer to next pollcat object in list, or NULL at end of list + */ +struct pollcat *pollcat_iter_next (void) +{ + struct pollcat *ret = pollcat_iter_curs; + + if ( ret ) + pollcat_iter_curs = ret->next; + + return ret; +} + + +/** Loop wrapper function + * + * This should be called as the test in a while() loop in main. Internally it will: + * - check whether pollcat_loop_exit() has been called, and return 0 if so + * - call pollcat_timer_reduce_timeout() to improve timer latency + * - call ops.prepare() on each pollcat object in the internal iterator list + * - call pollcat_poll() and optionally save the return value in poll-ret + * - call pollcat_timer_dispatch() to dispatch any expired timers + * - call ops.service() on each pollcat object in the internal iterator list + * - return nonzero for next loop + * + * \param poll_ret Optional pointer to int for return value from poll() call + * + * \return nonzero if main loop should continue, 0 if it should break + */ +int pollcat_loop (int *poll_ret) +{ + struct pollcat *walk; + int ret; + + /* check whether pollcat_loop_exit() has been called, and return 0 if so */ + if ( pollcat_loop_stop ) + return 0; + + /* call pollcat_timer_reduce_timeout() to improve timer latency */ + pollcat_timer_reduce_timeout(); + + /* call ops.prepare() on each pollcat object in the internal iterator list */ + for ( walk = pollcat_iter_head; walk; walk = walk->next ) + if ( walk->ops && walk->ops->prepare ) + walk->ops->prepare(walk); + + /* call pollcat_poll() and optionally save the return value in poll-ret */ + ret = pollcat_poll(); + if ( poll_ret ) + *poll_ret = ret; + + /* call pollcat_timer_dispatch() to dispatch any expired timers */ + pollcat_timer_dispatch(); + + /* call ops.service() on each pollcat object in the internal iterator list */ + for ( walk = pollcat_iter_head; walk; walk = walk->next ) + if ( walk->ops && walk->ops->service ) + walk->ops->service(walk); + + /* return nonzero for next loop */ + return 1; +} + + +/** Cause pollcat_loop() to return 0 on its next call + */ +void pollcat_loop_exit (void) +{ + pollcat_loop_stop = 1; +} + diff --git a/src/timer.c b/src/timer.c new file mode 100644 index 0000000..9a38419 --- /dev/null +++ b/src/timer.c @@ -0,0 +1,240 @@ +/** Millisecond-resolution event timers + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#include +#include +#include +#include +#include +#include + +#include +#include "private.h" + + +/** Active timer list is kept as a sorted, doubly-linked list. The next timer due is + * always the head. */ +static struct pollcat_timer *timer_head = NULL; +static struct pollcat_timer *timer_tail = NULL; + +/** Maximum number of times to run the dispatch loop, set to -1 for no limit */ +int pollcat_timer_dispatch_max = 100; + +/** Grace period in milliseconds for late timers, set to 0 for exact match */ +pollcat_time_t pollcat_timer_dispatch_thresh = 10; + + +/** Returns the monotonic clock in milliseconds */ +static pollcat_time_t pollcat_now (void) +{ + struct timespec ts; + pollcat_time_t now; + int ret = clock_gettime(CLOCK_MONOTONIC, &ts); + + POLLCAT_ASSERT(0 == ret); + + now = ts.tv_sec; + now *= 1000; + now += ts.tv_nsec / 1000000; + + return now; +} + + +/** Detach a timer from the active list + * + * \param timer Pointer to timer struct + */ +void pollcat_timer_detach (struct pollcat_timer *timer) +{ + if ( timer->prev ) + { + POLLCAT_ASSERT(timer->prev->next == timer); + timer->prev->next = timer->next; + } + else if ( timer == timer_head ) + timer_head = timer->next; + + if ( timer->next ) + { + POLLCAT_ASSERT(timer->next->prev == timer); + timer->next->prev = timer->prev; + } + else if ( timer == timer_tail ) + timer_tail = timer->prev; + + timer->prev = timer->next = NULL; +} + + +/** Attach or re-attach a timer to the active list + * + * \param timer Pointer to timer struct + * \param msec Delay in milliseconds + * \param func Callback function + * \param arg Argument to callback function + */ +void pollcat_timer_attach (struct pollcat_timer *timer, + pollcat_time_t msec, + pollcat_timer_f func, + void *arg) +{ + // add the delay to the timeofday and update the due date and other fields + timer->due = pollcat_now(); + timer->due += msec; + if ( func != timer->func ) timer->func = func; + if ( arg != timer->arg ) timer->arg = arg; + + // don't rely on the caller doing this + pollcat_timer_detach(timer); + + POLLCAT_ASSERT(!(timer_tail && !timer_head)); + POLLCAT_ASSERT(!(!timer_tail && timer_head)); + + // empty list: set timer_head and timer_tail + if ( !timer_head ) + { + timer_head = timer_tail = timer; + timer->prev = timer->next = NULL; + return; + } + + // smaller than timer_head, insert before timer_head + if ( timer->due <= timer_head->due ) + { + POLLCAT_ASSERT(!timer_head->prev); + + timer->prev = timer_head->prev; // NULL + timer->next = timer_head; + timer_head->prev = timer; + timer_head = timer; + return; + } + + // greater than timer_tail, append after timer_tail + if ( timer->due >= timer_tail->due ) + { + POLLCAT_ASSERT(!timer_tail->next); + + timer->prev = timer_tail; + timer->next = timer_tail->next; // NULL + timer_tail->next = timer; + timer_tail = timer; + return; + } + + // walk the list to insert + int cycles = 10; + struct pollcat_timer *walk = timer_head; + while ( walk->next ) + { + POLLCAT_ASSERT(walk->due <= walk->next->due); + + if ( timer->due >= walk->due && timer->due <= walk->next->due ) + { + timer->prev = walk; + timer->next = walk->next; + if ( walk->next ) + walk->next->prev = timer; + else + timer_tail = timer; + walk->next = timer; + return; + } + + cycles--; + POLLCAT_ASSERT(cycles); + + walk = walk->next; + } + + POLLCAT_ASSERT(0); +} + + +/** Returns nonzero if timer is attached + * + * \param timer Pointer to timer struct + * + * \return >0 if timer is attached + */ +int pollcat_timer_is_attached (struct pollcat_timer *timer) +{ + if ( timer == timer_head ) + return 1; + + if ( timer == timer_tail ) + return 2; + + if ( timer->next ) + return 3; + + if ( timer->prev ) + return 4; + + return 0; +} + + +/** Reduce the poll() timeout + * + * This should be called each main loop before the pollcat_poll() call, so that a ready + * timer isn't delayed. + */ +void pollcat_timer_reduce_timeout (void) +{ + if ( !timer_head ) + return; + + pollcat_time_t due = timer_head->due; + due -= pollcat_now(); + + pollcat_time_reduce(due); +} + + +/** Dispatch ready timers + */ +void pollcat_timer_dispatch (void) +{ + int max = pollcat_timer_dispatch_max; + + while ( timer_head && max-- ) + { + pollcat_time_t due = pollcat_now(); + + due -= timer_head->due; + if ( due > pollcat_timer_dispatch_thresh ) + return; + + // detach the head + struct pollcat_timer *t = timer_head; + pollcat_timer_detach(t); + + // safety check on the callback function + if ( !t->func ) + return; + + // upcall + t->func(t->arg); + } +} + diff --git a/tests/.gitignore b/tests/.gitignore new file mode 100644 index 0000000..6b724a0 --- /dev/null +++ b/tests/.gitignore @@ -0,0 +1,3 @@ +/poll +/struct +/timer diff --git a/tests/Makefile b/tests/Makefile new file mode 100644 index 0000000..b4011e5 --- /dev/null +++ b/tests/Makefile @@ -0,0 +1,73 @@ +# Test stubs Makefile +# +# This file is part of the Pollcat Library. +# Copyright (C) 2022 Expatria Technologies Inc. +# Contact: Morgan Hughes +# +# The Pollcat Library is free software: you can redistribute it and/or modify it under the +# terms of the the GNU Lesser General Public License as published by the Free Software +# Foundation; either version 3 of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, but WITHOUT ANY +# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. See the GNU General Public License for more details. +# +# You should have received copies of the GNU General Public License and the GNU Lesser +# General Public License along with the Pollcat Library. If not, see +# https://www.gnu.org/licenses/ +# +# vim:ts=4:noexpandtab + +# output targets +BINS := \ + poll \ + struct \ + timer + + +# "poll" app +POLL_OBJS := poll.o +POLL_LIBS := -lpollcat + +# "struct" app +STRUCT_OBJS := struct.o +STRUCT_LIBS := -lpollcat + +# "timer app +TIMER_OBJS := timer.o +TIMER_LIBS := -lpollcat + +CFLAGS += -I../include -Wall -Werror -g +CFLAGS += -D_LARGEFILE64_SOURCE +LFLAGS += -L.. -Wl,-rpath=$(shell cd .. && pwd) + +.PHONY: all install clean + +all: $(BINS) + @echo + +poll: $(POLL_OBJS) + $(CC) $(CFLAGS) $(LFLAGS) $^ $(POLL_LIBS) -o $@ + +struct: $(STRUCT_OBJS) + $(CC) $(CFLAGS) $(LFLAGS) $^ $(STRUCT_LIBS) -o $@ + +timer: $(TIMER_OBJS) + $(CC) $(CFLAGS) $(LFLAGS) $^ $(TIMER_LIBS) -o $@ + + +install: + false + +clean: + rm -f $(POLL_OBJS) + rm -f $(STRUCT_OBJS) + rm -f $(TIMER_OBJS) + rm -f $(BINS) + +%.i: %.c + $(CC) $(CFLAGS) -E $< -o $@ + +%.o: %.c + $(CC) $(CFLAGS) -c $< -o $@ + diff --git a/tests/poll.c b/tests/poll.c new file mode 100644 index 0000000..4862ced --- /dev/null +++ b/tests/poll.c @@ -0,0 +1,154 @@ +/** Pollcat test stub + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include + + +/** control for main loop for orderly shutdown */ +static int main_loop = 1; +static void signal_fatal (int signum) +{ + fprintf(stderr, "Fatal signal %d, exit loop\n", signum); + main_loop = 0; +} + +static void stop (const char *fmt, ...); + +extern char *__progname; +static void usage (void) +{ + printf("Usage: %s -v [-t timeout]\n" + "-v Verbose (set all modules to debug, enable trace)\n" + "-t timeout Timeout for poll() calls (ms)\n" + "", + __progname); + exit(1); +} + +int main (int argc, char **argv) +{ + int ret = 0; + short revents; + + // basic arguments parsing + int opt; + while ( (opt = getopt(argc, argv, "vt:")) != -1 ) + switch ( opt ) + { + case 'v': + break; + + case 't': + pollcat_time_base = atoi(optarg); + break; + + default: + usage(); + } + + pollcat_fd_add(fileno(stdin), POLLIN); + + signal(SIGTERM, signal_fatal); + signal(SIGINT, signal_fatal); + + // reopen stdout/stderr before making stdin non-blocking + char tty[256]; + memset(tty, 0, sizeof(tty)); + if ( readlink("/proc/self/fd/1", tty, sizeof(tty)) > 0 ) + { + if ( !freopen(tty, "w", stdout) || !freopen(tty, "w", stderr) ) + perror(tty); + setbuf(stderr, NULL); + } + + // set stdin nonblocking + int flags = fcntl(fileno(stdin), F_GETFL); + if ( flags < 0 ) + stop("fcntl(0, F_GETFL)"); + if ( fcntl(fileno(stdin), F_SETFL, flags | O_NONBLOCK) < 0 ) + stop("fcntl(0, F_SETFL)"); + + // save old terminal modes and make raw + struct termios tio_old; + if ( tcgetattr(fileno(stdin), &tio_old) ) + stop("tcgetattr(0, &tio_old)"); + + struct termios tio_new = tio_old; + tio_new.c_lflag &= ~(ECHO|ICANON); + if ( tcsetattr(fileno(stdin), TCSANOW, &tio_new) ) + stop("tcsetattr(0, TCSANOW, &tio_new)"); + + while ( main_loop ) + { + if ( (ret = pollcat_poll()) < 0 ) + { + perror("poll()"); + break; + } + else if ( !ret ) + continue; + + revents = pollcat_revents(fileno(stdin)); + assert(revents > -1); + if ( revents & POLLIN ) + { + char buff[16]; + + memset(buff, 0, sizeof(buff)); + ret = read(fileno(stdin), buff, sizeof(buff) - 1); + fprintf(stderr, "recv(%d): '%s'\n", ret, buff); + } + } + + if ( fcntl(0, F_SETFL, flags) < 0 ) + stop("fcntl(0, F_SETFL)"); + + if ( tcsetattr(0, TCSANOW, &tio_old) ) + stop("tcsetattr(0, TCSANOW, &tio_old)"); + + return 0; +} + +static void stop (const char *fmt, ...) +{ + int err = errno; + va_list ap; + + va_start(ap, fmt); + vfprintf(stderr, fmt, ap); + va_end(ap); + + fprintf(stderr, ": %s\n", strerror(err)); + exit(1); +} + diff --git a/tests/struct.c b/tests/struct.c new file mode 100644 index 0000000..7cd6421 --- /dev/null +++ b/tests/struct.c @@ -0,0 +1,196 @@ +/** Pollcat test stub + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include + + +static void stdin_service (struct pollcat *cat) +{ + char buff[16]; + int ret; + int idx; + + if ( !(pollcat_revents(fileno(stdin)) & POLLIN) ) + return; + + memset(buff, 0, sizeof(buff)); + if ( (ret = read(fileno(stdin), buff, sizeof(buff) - 1)) < 0 ) + { + fprintf(stderr, "recv(%d): %s", ret, strerror(errno)); + pollcat_loop_exit(); + return; + } + + fprintf(stderr, "recv(%d): '", ret); + for ( idx = 0; idx < ret; idx++ ) + if ( isprint(buff[idx]) ) + fputc(buff[idx], stderr); + else + fprintf(stderr, "\\x%02x", buff[idx]); + fputs("'\n", stderr); + + if ( ret ) + switch ( tolower(buff[0]) ) + { + case 'q': + case '\033': + case '\03': + fprintf(stderr, "shutting down\n"); + pollcat_loop_exit(); + return; + } +} + +const struct pollcat_ops stdin_ops = +{ + .service = stdin_service, +}; + +struct pollcat stdin_cat = +{ + .ops = &stdin_ops, +}; + + +struct pollcat_timer timer = { 0 }; +static void callback (void *arg) +{ + printf("timer callback\n"); + pollcat_timer_attach(&timer, 5000, callback, NULL); +} + + +/** control for main loop for orderly shutdown */ +static void signal_fatal (int signum) +{ + fprintf(stderr, "Fatal signal %d, exit loop\n", signum); + pollcat_loop_exit(); +} + +static void stop (const char *fmt, ...); + +extern char *__progname; +static void usage (void) +{ + printf("Usage: %s -v [-t timeout]\n" + "-v Verbose (set all modules to debug, enable trace)\n" + "-t timeout Timeout for poll() calls (ms)\n" + "", + __progname); + exit(1); +} + +int main (int argc, char **argv) +{ + int ret; + + // basic arguments parsing + int opt; + while ( (opt = getopt(argc, argv, "vt:")) != -1 ) + switch ( opt ) + { + case 'v': + break; + + case 't': + pollcat_time_base = atoi(optarg); + break; + + default: + usage(); + } + + signal(SIGTERM, signal_fatal); + signal(SIGINT, signal_fatal); + + // reopen stdout/stderr before making stdin non-blocking + char tty[256]; + memset(tty, 0, sizeof(tty)); + if ( readlink("/proc/self/fd/1", tty, sizeof(tty)) > 0 ) + { + if ( !freopen(tty, "w", stdout) || !freopen(tty, "w", stderr) ) + perror(tty); + setbuf(stderr, NULL); + } + + // set stdin nonblocking + int flags = fcntl(fileno(stdin), F_GETFL); + if ( flags < 0 ) + stop("fcntl(0, F_GETFL)"); + if ( fcntl(fileno(stdin), F_SETFL, flags | O_NONBLOCK) < 0 ) + stop("fcntl(0, F_SETFL)"); + + // save old terminal modes and make raw + struct termios tio_old; + if ( tcgetattr(fileno(stdin), &tio_old) ) + stop("tcgetattr(0, &tio_old)"); + + struct termios tio_new = tio_old; + tio_new.c_lflag &= ~(ECHO|ICANON); + if ( tcsetattr(fileno(stdin), TCSANOW, &tio_new) ) + stop("tcsetattr(0, TCSANOW, &tio_new)"); + + pollcat_fd_add(fileno(stdin), POLLIN); + pollcat_iter_add(&stdin_cat); + + pollcat_timer_attach(&timer, 5000, callback, NULL); + + while ( pollcat_loop(&ret) ) + { + } + + pollcat_iter_remove(&stdin_cat); + pollcat_fd_remove(fileno(stdin)); + + if ( fcntl(0, F_SETFL, flags) < 0 ) + stop("fcntl(0, F_SETFL)"); + + if ( tcsetattr(0, TCSANOW, &tio_old) ) + stop("tcsetattr(0, TCSANOW, &tio_old)"); + + return 0; +} + +static void stop (const char *fmt, ...) +{ + int err = errno; + va_list ap; + + va_start(ap, fmt); + vfprintf(stderr, fmt, ap); + va_end(ap); + + fprintf(stderr, ": %s\n", strerror(err)); + exit(1); +} + diff --git a/tests/timer.c b/tests/timer.c new file mode 100644 index 0000000..39ff0a9 --- /dev/null +++ b/tests/timer.c @@ -0,0 +1,169 @@ +/** Pollcat test stub - timers + * + * This file is part of the Pollcat Library. + * Copyright (C) 2022 Expatria Technologies Inc. + * Contact: Morgan Hughes + * + * The Pollcat Library is free software: you can redistribute it and/or modify it under + * the terms of the the GNU Lesser General Public License as published by the Free + * Software Foundation; either version 3 of the License, or (at your option) any later + * version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT ANY + * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + * PARTICULAR PURPOSE. See the GNU General Public License for more details. + * + * You should have received copies of the GNU General Public License and the GNU Lesser + * General Public License along with the Pollcat Library. If not, see + * https://www.gnu.org/licenses/ + * + * vim:ts=4:noexpandtab + */ +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include + + +/** control for main loop for orderly shutdown */ +static int main_loop = 1; +static void signal_fatal (int signum) +{ + fprintf(stderr, "Fatal signal %d, exit loop\n", signum); + main_loop = 0; +} + +static void stop (const char *fmt, ...); + +struct pollcat_timer timer = { 0 }; +static void callback (void *arg) +{ + printf("timer callback\n"); + pollcat_timer_attach(&timer, 333, callback, NULL); +} + + +extern char *__progname; +static void usage (void) +{ + printf("Usage: %s -v [-t timeout]\n" + "-v Verbose (set all modules to debug, enable trace)\n" + "-t timeout Timeout for poll() calls (ms)\n" + "", + __progname); + exit(1); +} + +int main (int argc, char **argv) +{ + int ret = 0; + short revents; + + // basic arguments parsing + int opt; + while ( (opt = getopt(argc, argv, "vt:")) != -1 ) + switch ( opt ) + { + case 'v': + break; + + case 't': + pollcat_time_base = atoi(optarg); + break; + + default: + usage(); + } + + pollcat_fd_add(fileno(stdin), POLLIN); + + signal(SIGTERM, signal_fatal); + signal(SIGINT, signal_fatal); + + // reopen stdout/stderr before making stdin non-blocking + char tty[256]; + memset(tty, 0, sizeof(tty)); + if ( readlink("/proc/self/fd/1", tty, sizeof(tty)) > 0 ) + { + if ( !freopen(tty, "w", stdout) || !freopen(tty, "w", stderr) ) + perror(tty); + setbuf(stderr, NULL); + } + + // set stdin nonblocking + int flags = fcntl(fileno(stdin), F_GETFL); + if ( flags < 0 ) + stop("fcntl(0, F_GETFL)"); + if ( fcntl(fileno(stdin), F_SETFL, flags | O_NONBLOCK) < 0 ) + stop("fcntl(0, F_SETFL)"); + + // save old terminal modes and make raw + struct termios tio_old; + if ( tcgetattr(fileno(stdin), &tio_old) ) + stop("tcgetattr(0, &tio_old)"); + + struct termios tio_new = tio_old; + tio_new.c_lflag &= ~(ECHO|ICANON); + if ( tcsetattr(fileno(stdin), TCSANOW, &tio_new) ) + stop("tcsetattr(0, TCSANOW, &tio_new)"); + + while ( main_loop ) + { + pollcat_timer_reduce_timeout(); + + if ( (ret = pollcat_poll()) < 0 ) + { + perror("poll()"); + break; + } + + pollcat_timer_dispatch(); + + if ( !ret ) + continue; + + revents = pollcat_revents(fileno(stdin)); + assert(revents > -1); + if ( revents & POLLIN ) + { + char buff[16]; + + memset(buff, 0, sizeof(buff)); + ret = read(fileno(stdin), buff, sizeof(buff) - 1); + fprintf(stderr, "recv(%d): '%s'\n", ret, buff); + + pollcat_timer_attach(&timer, 333, callback, NULL); + } + } + + if ( fcntl(0, F_SETFL, flags) < 0 ) + stop("fcntl(0, F_SETFL)"); + + if ( tcsetattr(0, TCSANOW, &tio_old) ) + stop("tcsetattr(0, TCSANOW, &tio_old)"); + + return 0; +} + +static void stop (const char *fmt, ...) +{ + int err = errno; + va_list ap; + + va_start(ap, fmt); + vfprintf(stderr, fmt, ap); + va_end(ap); + + fprintf(stderr, ": %s\n", strerror(err)); + exit(1); +} +