{"id":15286181,"url":"https://github.com/sysread/ipc-simple","last_synced_at":"2025-03-23T21:22:05.880Z","repository":{"id":56834156,"uuid":"259378709","full_name":"sysread/IPC-Simple","owner":"sysread","description":"Easy to use non-blocking IPC for perl","archived":false,"fork":false,"pushed_at":"2020-12-08T16:04:56.000Z","size":118,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-14T23:02:34.806Z","etag":null,"topics":["async","ipc","non-blocking","perl","process"],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sysread.png","metadata":{"files":{"readme":"README.pod","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-27T15:49:06.000Z","updated_at":"2020-12-08T16:04:53.000Z","dependencies_parsed_at":"2022-09-09T21:10:38.038Z","dependency_job_id":null,"html_url":"https://github.com/sysread/IPC-Simple","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysread%2FIPC-Simple","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysread%2FIPC-Simple/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysread%2FIPC-Simple/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysread%2FIPC-Simple/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sysread","download_url":"https://codeload.github.com/sysread/IPC-Simple/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245169935,"owners_count":20571980,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","ipc","non-blocking","perl","process"],"created_at":"2024-09-30T15:10:54.553Z","updated_at":"2025-03-23T21:22:05.853Z","avatar_url":"https://github.com/sysread.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"=pod\n\n=encoding UTF-8\n\n=head1 NAME\n\nIPC::Simple - simple, non-blocking IPC\n\n=head1 VERSION\n\nversion 0.09\n\n=head1 SYNOPSIS\n\n  use IPC::Simple qw(spawn);\n\n  my $ssh = spawn ['ssh', $host];\n\n  if ($ssh-\u003elaunch) {\n    $ssh-\u003esend('ls -lah');          # get directory listing\n    $ssh-\u003esend('echo');             # signal our loop that the listing is done\n\n    while (my $msg = $ssh-\u003erecv) {  # echo's output will be an empty string\n      if ($msg-\u003eerror) {            # I/O error\n        croak $msg;\n      }\n      elsif ($msg-\u003estderr) {        # output to STDERR\n        warn $msg;\n      }\n      elsif ($msg-\u003estdout) {        # output to STDOUT\n        say $msg;\n      }\n    }\n\n    $ssh-\u003esend('exit');             # terminate the connection\n    $ssh-\u003ejoin;                     # wait for the process to terminate\n  }\n\n=head1 DESCRIPTION\n\nProvides a simplified interface for managing and kibbitzing with a child\nprocess.\n\n=head1 EXPORTS\n\nNothing is exported by default, but the following subroutines may be requested\nfor import.\n\n=head2 spawn\n\nReturns a new C\u003cIPC::Simple\u003e object. The first argument is either the command\nline string or an array ref of the command and its arguments. Any remaining\narguments are treated as keyword pairs for the constructor.\n\nC\u003cspawn\u003e does I\u003cnot\u003e launch the process.\n\n  my $proc = spawn [\"echo\", \"hello world\"], eol =\u003e \"\\n\";\n\nIs equivalent to:\n\n  my $proc = IPC::Simple-\u003enew(\n    cmd =\u003e [\"echo\", \"hello world\"],\n    eol =\u003e \"\\n\",\n  );\n\n=head2 process_group\n\nBuilds a combined message queue for a group of I\u003cunlaunched\u003e C\u003cIPC::Simple\u003e\nobjects that may be used to process all of the group's messages together.\nReturns an L\u003cIPC::Simple::Group\u003e.\n\n  my $group = process_group(\n    spawn('...', name =\u003e 'foo'),\n    spawn('...', name =\u003e 'bar'),\n    spawn('...', name =\u003e 'baz'),\n  );\n\n  $group-\u003elaunch;\n\n  while (my $msg = $group-\u003erecv) {\n    if ($msg-\u003esource-\u003ename eq 'foo') {\n      ...\n    }\n  }\n\n  $group-\u003eterminate;\n  $group-\u003ejoin;\n\n=head1 METHODS\n\n=head1 new\n\nCreates a new C\u003cIPC::Simple\u003e process object. The process is not immediately\nlaunched; see L\u003c/launch\u003e.\n\n=head2 constructor arguments\n\n=over\n\n=item cmd\n\nThe command to launch in a child process. This may be specified as the entire\ncommand string or as an array ref of the command and its arguments.\n\n=item name\n\nOptionally specify a name for this process. This is useful when grouping\nprocesses together to identify the source of a message. If not provided, the\ncommand string is used by default.\n\n=item eol\n\nThe end-of-line character to print at the end of each call to L\u003c/send\u003e.\nDefaults to C\u003c\"\\n\"\u003e.\n\n=item recv_cb\n\nOptionally, a callback may be specified to receive messages as they arrive.\n\n  my $proc = spawn [...], recv_cb =\u003e sub{\n    my $msg = shift;\n    my $proc = $msg-\u003esource;\n    ...\n  };\n\n  $proc-\u003elaunch;\n  $proc-\u003ejoin;\n\n=item term_cb\n\nAnother optional callback to be triggered when the process is terminated. The\nexit status and exit code are available once the L\u003c/join\u003e method has been\ncalled on the process object passed to the callback.\n\n  my $proc = spawn [...], term_cb =\u003e sub{\n    my $proc = shift;\n    $proc-\u003ejoin;\n\n    my $code = $proc-\u003eexit_code;\n    my $status = $proc-\u003eexit_status;\n    ...\n  };\n\n=back\n\n=head2 pid\n\nOnce launched, returns the pid of the child process.\n\n=head2 exit_status\n\nOnce a child process exits, this is set to the exit status (C\u003c$?\u003e) of the child\nprocess.\n\n=head2 exit_code\n\nOnce a child process has terminated, this is set to the exit code of the child\nprocess.\n\n=head2 launch\n\nStarts the child process. Returns true on success, croaks on failure to launch\nthe process.\n\n=head2 terminate\n\nSends the child process a C\u003cSIGTERM\u003e. Returns immediately. Use L\u003c/join\u003e to wait\nfor the process to finish. An optional timeout may be specified in fractional\nseconds, after which the child process is issued a C\u003cSIGKILL\u003e.\n\n=head2 signal\n\nSends a signal to the child process. Accepts a single argument, the signal type\nto send.\n\n  $proc-\u003esignal('TERM');\n\n=head2 join\n\nBlocks until the child process has exited.\n\n=head2 send\n\nSends a string of text to the child process. The string will be appended with\nthe value of L\u003c/eol\u003e.\n\n=head2 recv\n\nWaits for and returns the next line of output from the process, which may be\nfrom C\u003cSTDOUT\u003e, from C\u003cSTDERR\u003e, or it could be an error message resulting from\nan I/O error while communicating with the process (e.g. a C\u003cSIGPIPE\u003e or\nabnormal termination).\n\nEach message returned by C\u003crecv\u003e is an object overloaded so that it can be\ntreated as a string as well as a L\u003cIPC::Simple::Message\u003e with the following\nsignificant methods:\n\n=over\n\n=item source\n\nThe C\u003cIPC::Simple\u003e object from which the message originated.\n\n=item stdout\n\nTrue when the message came from the child process' C\u003cSTDOUT\u003e.\n\n=item stderr\n\nTrue when the message came from the child process' C\u003cSTDERR\u003e.\n\n=item error\n\nTrue when the message is a sub-process communication error.\n\n=back\n\n=head1 DEBUGGING\n\nC\u003cIPC::Simple\u003e will emit highly verbose messages to C\u003cSTDERR\u003e if the\nenvironment variable C\u003cIPC_SIMPLE_DEBUG\u003e is set to a true value.\n\n=head1 MSWIN32 SUPPORT\n\nNope.\n\n=head1 AUTHOR\n\nJeff Ober \u003csysread@fastmail.fm\u003e\n\n=head1 COPYRIGHT AND LICENSE\n\nThis software is copyright (c) 2020 by Jeff Ober.\n\nThis is free software; you can redistribute it and/or modify it under\nthe same terms as the Perl 5 programming language system itself.\n\n=cut\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsysread%2Fipc-simple","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsysread%2Fipc-simple","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsysread%2Fipc-simple/lists"}