{ "content": [ { "type": "text", "text": "# Test2::Util (perldoc)\n\n**Summary:** Test2::Util - Tools used by Test2 and friends.\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **DESCRIPTION** (2 lines)\n- **EXPORTS** (85 lines)\n- **SOURCE** (2 lines)\n- **MAINTAINERS** (2 lines)\n- **AUTHORS** (3 lines)\n- **COPYRIGHT** (7 lines)\n\n## Full Content\n\n### NAME\n\nTest2::Util - Tools used by Test2 and friends.\n\n### DESCRIPTION\n\nCollection of tools used by Test2 and friends.\n\n### EXPORTS\n\nAll exports are optional. You must specify subs to import.\n\n($success, $error) = try { ... }\nEval the codeblock, return success or failure, and the error message. This code protects $@\nand $!, they will be restored by the end of the run. This code also temporarily blocks\n$SIG{DIE} handlers.\n\nprotect { ... }\nSimilar to try, except that it does not catch exceptions. The idea here is to protect $@ and\n$! from changes. $@ and $! will be restored to whatever they were before the run so long as\nit is successful. If the run fails $! will still be restored, but $@ will contain the\nexception being thrown.\n\nCANFORK\nTrue if this system is capable of true or pseudo-fork.\n\nCANREALLYFORK\nTrue if the system can really fork. This will be false for systems where fork is emulated.\n\nCANTHREAD\nTrue if this system is capable of using threads.\n\nUSETHREADS\nReturns true if threads are enabled, false if they are not.\n\ngettid\nThis will return the id of the current thread when threads are enabled, otherwise it returns\n0.\n\nmy $file = pkgtofile($package)\nConvert a package name to a filename.\n\n$string = ipcseparator()\nGet the IPC separator. Currently this is always the string '~'.\n\n$string = genuid()\nGenerate a unique id (NOT A UUID). This will typically be the process id, the thread id, the\ntime, and an incrementing integer all joined with the \"ipcseparator()\".\n\nThese ID's are unique enough for most purposes. For identical ids to be generated you must\nhave 2 processes with the same PID generate IDs at the same time with the same current state\nof the incrementing integer. This is a perfectly reasonable thing to expect to happen across\nmultiple machines, but is quite unlikely to happen on one machine.\n\nThis can fail to be unique if a process generates an id, calls exec, and does it again after\nthe exec and it all happens in less than a second. It can also happen if the systems process\nid's cycle in less than a second allowing 2 different programs that use this generator to\nrun with the same PID in less than a second. Both these cases are sufficiently unlikely. If\nyou need universally unique ids, or ids that are unique in these conditions, look at\nData::UUID.\n\n($ok, $err) = dorename($oldname, $newname)\nRename a file, this wraps \"rename()\" in a way that makes it more reliable cross-platform\nwhen trying to rename files you recently altered.\n\n($ok, $err) = dounlink($filename)\nUnlink a file, this wraps \"unlink()\" in a way that makes it more reliable cross-platform\nwhen trying to unlink files you recently altered.\n\n($ok, $err) = trysigmask { ... }\nComplete an action with several signals masked, they will be unmasked at the end allowing\nany signals that were intercepted to get handled.\n\nThis is primarily used when you need to make several actions atomic (against some signals\nanyway).\n\nSignals that are intercepted:\n\nSIGINT\nSIGALRM\nSIGHUP\nSIGTERM\nSIGUSR1\nSIGUSR2\n\nNOTES && CAVEATS\n5.10.0\nPerl 5.10.0 has a bug when compiled with newer gcc versions. This bug causes a segfault\nwhenever a new thread is launched. Test2 will attempt to detect this, and note that the\nsystem is not capable of forking when it is detected.\n\nDevel::Cover\nDevel::Cover does not support threads. CANTHREAD will return false if Devel::Cover is\nloaded before the check is first run.\n\n### SOURCE\n\nThe source code repository for Test2 can be found at http://github.com/Test-More/test-more/.\n\n### MAINTAINERS\n\nChad Granum \n\n### AUTHORS\n\nChad Granum \nKent Fredric \n\n### COPYRIGHT\n\nCopyright 2020 Chad Granum .\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\nSee http://dev.perl.org/licenses/\n\n" } ], "structuredContent": { "command": "Test2::Util", "section": "", "mode": "perldoc", "summary": "Test2::Util - Tools used by Test2 and friends.", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 2, "subsections": [] }, { "name": "EXPORTS", "lines": 85, "subsections": [] }, { "name": "SOURCE", "lines": 2, "subsections": [] }, { "name": "MAINTAINERS", "lines": 2, "subsections": [] }, { "name": "AUTHORS", "lines": 3, "subsections": [] }, { "name": "COPYRIGHT", "lines": 7, "subsections": [] } ], "sections": { "NAME": { "content": "Test2::Util - Tools used by Test2 and friends.\n", "subsections": [] }, "DESCRIPTION": { "content": "Collection of tools used by Test2 and friends.\n", "subsections": [] }, "EXPORTS": { "content": "All exports are optional. You must specify subs to import.\n\n($success, $error) = try { ... }\nEval the codeblock, return success or failure, and the error message. This code protects $@\nand $!, they will be restored by the end of the run. This code also temporarily blocks\n$SIG{DIE} handlers.\n\nprotect { ... }\nSimilar to try, except that it does not catch exceptions. The idea here is to protect $@ and\n$! from changes. $@ and $! will be restored to whatever they were before the run so long as\nit is successful. If the run fails $! will still be restored, but $@ will contain the\nexception being thrown.\n\nCANFORK\nTrue if this system is capable of true or pseudo-fork.\n\nCANREALLYFORK\nTrue if the system can really fork. This will be false for systems where fork is emulated.\n\nCANTHREAD\nTrue if this system is capable of using threads.\n\nUSETHREADS\nReturns true if threads are enabled, false if they are not.\n\ngettid\nThis will return the id of the current thread when threads are enabled, otherwise it returns\n0.\n\nmy $file = pkgtofile($package)\nConvert a package name to a filename.\n\n$string = ipcseparator()\nGet the IPC separator. Currently this is always the string '~'.\n\n$string = genuid()\nGenerate a unique id (NOT A UUID). This will typically be the process id, the thread id, the\ntime, and an incrementing integer all joined with the \"ipcseparator()\".\n\nThese ID's are unique enough for most purposes. For identical ids to be generated you must\nhave 2 processes with the same PID generate IDs at the same time with the same current state\nof the incrementing integer. This is a perfectly reasonable thing to expect to happen across\nmultiple machines, but is quite unlikely to happen on one machine.\n\nThis can fail to be unique if a process generates an id, calls exec, and does it again after\nthe exec and it all happens in less than a second. It can also happen if the systems process\nid's cycle in less than a second allowing 2 different programs that use this generator to\nrun with the same PID in less than a second. Both these cases are sufficiently unlikely. If\nyou need universally unique ids, or ids that are unique in these conditions, look at\nData::UUID.\n\n($ok, $err) = dorename($oldname, $newname)\nRename a file, this wraps \"rename()\" in a way that makes it more reliable cross-platform\nwhen trying to rename files you recently altered.\n\n($ok, $err) = dounlink($filename)\nUnlink a file, this wraps \"unlink()\" in a way that makes it more reliable cross-platform\nwhen trying to unlink files you recently altered.\n\n($ok, $err) = trysigmask { ... }\nComplete an action with several signals masked, they will be unmasked at the end allowing\nany signals that were intercepted to get handled.\n\nThis is primarily used when you need to make several actions atomic (against some signals\nanyway).\n\nSignals that are intercepted:\n\nSIGINT\nSIGALRM\nSIGHUP\nSIGTERM\nSIGUSR1\nSIGUSR2\n\nNOTES && CAVEATS\n5.10.0\nPerl 5.10.0 has a bug when compiled with newer gcc versions. This bug causes a segfault\nwhenever a new thread is launched. Test2 will attempt to detect this, and note that the\nsystem is not capable of forking when it is detected.\n\nDevel::Cover\nDevel::Cover does not support threads. CANTHREAD will return false if Devel::Cover is\nloaded before the check is first run.\n", "subsections": [] }, "SOURCE": { "content": "The source code repository for Test2 can be found at http://github.com/Test-More/test-more/.\n", "subsections": [] }, "MAINTAINERS": { "content": "Chad Granum \n", "subsections": [] }, "AUTHORS": { "content": "Chad Granum \nKent Fredric \n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright 2020 Chad Granum .\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\nSee http://dev.perl.org/licenses/\n", "subsections": [] } } } }