Skip to content

modified / added documentation for lib/child_process.js #60459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
16lr wants to merge 1 commit into
base: main
Choose a base branch
from
Open

modified / added documentation for lib/child_process.js #60459

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 18 additions & 5 deletions lib/child_process.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,7 @@ function fork(modulePath, args = [], options) {
// Get options and args arguments.
let execArgv;

//validating args as an array
if (args == null) {
args = [];
} else if (typeof args === 'object' && !ArrayIsArray(args)) {
Expand Down Expand Up @@ -159,6 +160,7 @@ function fork(modulePath, args = [], options) {

args = [...execArgv, modulePath, ...args];

//converting options.stdio into a string
if (typeof options.stdio === 'string') {
options.stdio = stdioStringToArray(options.stdio, 'ipc');
} else if (!ArrayIsArray(options.stdio)) {
Expand Down Expand Up @@ -188,6 +190,7 @@ function _forkChild(fd, serializationMode) {
});
}

//validating command as a string
function normalizeExecArgs(command, options, callback) {
validateString(command, 'command');
validateArgumentNullCheck(command, 'command');
Expand Down Expand Up @@ -238,6 +241,7 @@ function exec(command, options, callback) {
opts.callback);
}

//Promise based API for accesing the child process
const customPromiseExecFunction = (orig) => {
return assignFunctionName(orig.name, function(...args) {
const { promise, resolve, reject } = PromiseWithResolvers();
Expand All @@ -263,9 +267,12 @@ ObjectDefineProperty(exec, promisify.custom, {
});

function normalizeExecFileArgs(file, args, options, callback) {
//making a new copy of the array
if (ArrayIsArray(args)) {
args = ArrayPrototypeSlice(args);
//checking if args is not null and it is a object
} else if (args != null && typeof args === 'object') {
//if args is an object then callback will be the options, options will be the args and args will not exist
callback = options;
options = args;
args = null;
Expand Down Expand Up @@ -346,6 +353,7 @@ function execFile(file, args, options, callback) {

options.killSignal = sanitizeKillSignal(options.killSignal);

//spawn a new child process
const child = spawn(file, args, {
cwd: options.cwd,
env: options.env,
Expand All @@ -357,6 +365,7 @@ function execFile(file, args, options, callback) {
windowsVerbatimArguments: !!options.windowsVerbatimArguments,
});

//setting the type of encoding that the user wants to use
let encoding;
const _stdout = [];
const _stderr = [];
Expand Down Expand Up @@ -424,6 +433,7 @@ function execFile(file, args, options, callback) {
callback(ex, stdout, stderr);
}

//if an error occurs in the process, it will call errorhandler to destroy the stdout and stderr streams before exiting
function errorhandler(e) {
ex = e;

Expand Down Expand Up @@ -985,6 +995,8 @@ function execFileSync(file, args, options) {
* }} [options]
* @returns {Buffer | string}
*/

//spawning a child process synchronously
function execSync(command, options) {
const opts = normalizeExecArgs(command, options, null);
const inheritStderr = !opts.options.stdio;
Expand All @@ -1002,38 +1014,39 @@ function execSync(command, options) {
return ret.stdout;
}


//validating if arg is a string and it is not containg null bytes
function validateArgumentNullCheck(arg, propName) {
if (typeof arg === 'string' && StringPrototypeIncludes(arg, '\u0000')) {
throw new ERR_INVALID_ARG_VALUE(propName, arg, 'must be a string without null bytes');
}
}


//validating multiple strings once the function is called.
function validateArgumentsNullCheck(args, propName) {
for (let i = 0; i < args.length; ++i) {
validateArgumentNullCheck(args[i], `${propName}[${i}]`);
}
}


//
function validateTimeout(timeout) {
if (timeout != null) {
validateInteger(timeout, 'timeout', 0);
}
}


//checking if it is a signed int.
function validateMaxBuffer(maxBuffer) {
if (maxBuffer != null) {
validateNumber(maxBuffer, 'options.maxBuffer', 0);
}
}


//trying to convert into a valid singla for killing it.
function sanitizeKillSignal(killSignal) {
if (typeof killSignal === 'string' || typeof killSignal === 'number') {
return convertToValidSignal(killSignal);
//if the arguments are not correctly we are throwing an error
} else if (killSignal != null) {
throw new ERR_INVALID_ARG_TYPE('options.killSignal',
['string', 'number'],
Expand Down