ipcSkillProcess

ipcSkillProcess( 
t_command 
[ t_hostName ] 
[ tsu_dataHandler ] 
[ tsu_errHandler ] 
[ tsu_postFunc ] 
[ t_logFile ] 
[ x_cmdDesc ] 
[ x_resDesc ] 
)
=> o_childId

Description

Invokes an operating system process capable of executing SKILL functions in the parent process and opens two additional channels to the child process that let the child send and receive the results of SKILL commands.

The maximum number of child processes is limited by the system resources and a warning message displays when the fileDescriptor limit is exceeded.

Sending Channel

The SKILL command channel is by default bound to file descriptor number 3 in the child process. In addition to whatever input and output the child process may perform, it can write SKILL executable commands on this descriptor that are in turn sent to the parent to be executed. The parent executes these commands during the next cycle of SKILL’s top level without interrupting the current evaluation. The result of this execution is sent back to the child over the SKILL result channel, which is by default bound to file descriptor number 4 in the child process.

The defaults can be over-ridden by supplying the descriptors in the call to ipcSkillProcess. These descriptors must be declared and used by the child process, that is, the parent process cannot force the child process to use a particular pair of channels.

SKILL functions written into the SKILL command channel should have sound syntactic structures. For example,

Use parentheses when writing function calls, even for infix functions.
Ensure that all command expressions are separated by at least a single space character.
Command expressions with missing parentheses or incomplete strings can cause syntax errors in the SKILL interpreter, thereby causing other functions in the pipeline to fail.

Result Channel

The results of executing SKILL functions are sent back on the result channel (descriptor 4 by default). It is up to the child process to read from the result channel.

When using the Windows Operating System, because of limited buffer sizes, if the child process fails to read accumulated data from the result channel there is a chance that results will be discarded if the buffer fills up.

The buffer for the result channel is separate from all other buffers so the process does not have to empty the buffer if the results are not needed.

Arguments

t_command	Command to be executed locally or on a network node.
t_hostName	Specifies the network node. An empty string (`""`) for hostName means the process is run locally.
tsu_dataHandler, tsu_errHandler, tsu_postFunc	These call back functions can be given as strings, symbols or function objects. Handlers are called whenever the parent process receives data from the child process. Activation of handler calls occurs at the top level of SKILL; that is, it does not interrupt the current evaluation. Define handlers to accept two parameters: o_childId and t_data. Handlers are called with the childId of the child that sent the data and the data itself is packed into a SKILL string.
	If tsu_dataHandler is `nil`, the parent must use ipcReadProcess to read the data.
	tsu_dataHandler, tsu_errHandler correspond to a child’s stdout and stderr respectively.
	The tsu_postFunc function is called when a child terminates. It must be defined to accept two parameters: o_childId and x_exitStatus, where exitStatus is the value returned by the child process on exit. If tsu_postFunc is `nil`, the child’s health and exit status must be checked using the `ipcIsAliveProcess` and `ipcGetExitStatus` functions.
t_logFile	File that can be used to log all output from a child process.
	A child invoked with the t_logFile present starts its life duplicating its output to the log file and sending the data to the parent. If at any point the child is to be put in batch mode and its communications with the parent silenced, use `ipcActivateBatch`. Once in batch mode, the output of a child process is written to the logFile only. Subsequently, the messages to the parent can be turned back on using `ipcActivateMessages`. Using these two functions, a child process can be made to switch between the batch and active data passing states.
x_cmdDesc	SKILL command sending channel.
x_resDesc	SKILL result receiving channel.

Examples

Example 1

Suppose we have a C program, sample.c:

/**********************************************
* Sample process for executing SKILL commands
* in parent process.
**********************************************/
#include "stdio.h"
#define skill_cmd 3
#define skill_result 4

main(int argc, char **argv)
{
    int status;
    char s[100];

    sprintf(s, "%s", "(let () (println \"Hello world \") (1 + 1))"); 
    printf("Executing %s", s);
    fflush(stdout);
    status = write(skill_cmd, &s[0], strlen(s));
    status = read(skill_result, &s[0], 100);
    s[status] = '\0';
    printf("Result = %s",  s);
    fflush(stdout);
    exit(0);
}

Compile this into an executable named sample.exe. Then in SKILL:

      cid = ipcSkillProcess("sample.exe")
ipc:5
"Hello world"
      ipcReadProcess(cid)
"Executing (let () (println \"Hello world\") (1 + 1))"
      ipcReadProcess(cid)
"Result = (2)"
      cid->exitStatus
0

Example 2

/**********************************************
* Example of ipcSkillProcess using a Perl script.
**********************************************/
=== Perl script ===

#!/usr/bin/perl 
use IO::Handle;
use Fcntl;

# open descriptor 3 and ensure it flushes automatically
open(outPort, ">&3");
outPort->autoflush(1);
print outPort "(myTest)\n";

# open descriptor 4 and ensure it's non-blocking
open(inPort, "<&4");
fcntl(inPort,F_GETFL,$flags);
$flags|=O_NONBLOCK;
fcntl(inPort,F_SETFL,$flags);

# wait a bit and then read
sleep(2);
$inLine=<inPort>;
print "From Perl: $inLine\n";

=== SKILL script ===

procedure( testIpc()
   let( (child)
     printf("Executing ipc: %s\n" getCurrentTime())
     child=ipcSkillProcess("./test.perl")
     ipcWaitForProcess(child)
     printf("%s\n" ipcReadProcess(child 10))
   ) ;let
) ;procedure

procedure( myTest()
   prog( ()
      printf("Executed by Perl\n")
      return("123")
   ) ;prog
) ;procedure

Cadence Interprocess Communication SKILL Reference
Product Version IC23.1, June 2023