Port
Last updated
Was this helpful?
Last updated
Was this helpful?
This implementation of the meta-process allows running external programs and communicating with them using stdin and stdout. Communication can be performed in both text and binary formats.
To create a meta.Port
, you need to use the meta.CreatePort
function. It takes meta.PortOptions
as an argument, which allows specifying the following options:
Cmd
command to run
Args
arguments for the command
Env
environment variables for the program being executed
EnableEnvMeta
adds environment variables of the meta-process
EnableEnvOS
adds OS environment variables
Tag
can help distinguish between multiple meta-processes running with the same Cmd
/Args
Process
The name of the process that will handle meta.MessagePort*
messages. If not specified, all messages will be sent to the parent process. You can also use an act.Pool
process for distributing message handling
SplitFuncStdout
to specify a split-function. (uses Scanner
from the standard bufio
package) for processing data from stdout in text mode. By default, data is split by lines
SplitFuncStderr
to specify a split-function for the data from stderr
Binary
enables binary mode for the data from stdout. See for more information
Below is an example of creating and running the external program example-prog
using a meta-process meta.Port
:
The implementation of meta.Port
supports binary mode when working with stdin/stdout. To enable it, use the meta.PortOptions.Binary.Enable
option and specify the binary format parameters:
ReadBufferSize
sets the buffer size for reading. The default size is 8192
ReadBufferPool
defines a pool for message buffers. The Get
method should return an allocated buffer of type []byte
ReadChunk
enables auto-chunking mode, which splits the incoming stream into chunks according to the specified parameters. For more details, see Auto chunking
WriteBufferKeepAlive
enables the software keep-alive mechanism – a specified value will be automatically sent at the interval defined in the option WriteBufferKeepAlivePeriod
When binary mode is enabled, the SplitFuncStdout
option is ignored. However, stderr is processed in text mode, and you can use the SplitFuncStderr
option.
This feature allows automatically chunking the incoming stream in binary mode. The chunks can be of fixed length – to achieve this, you need to specify the chunk size using the FixedLength
option. For data with dynamic length, you must specify header parameters that will define the chunk length.
To enable the auto-chunking feature in binary mode, use the meta.PortOptions.Binary.ReadChunk.Enable
option, and specify the parameters for automatic data chunking using the following options:
FixedLength
allows you to set the length of chunks in the stdout. In this case, all Header*
options will be ignored. Leave this field with a zero value to work with dynamically sized chunks
HeaderSize
specifies the size of the header for dynamically sized chunks
HeaderLengthPosition
specifies the position in the header where the length is stored
HeaderLengthSize
specifies the size of the length in bytes (1, 2 or 4)
HeaderLengthIncludesHeader
specifies whether the length value includes the header size
MaxLength
allows you to set the maximum chunk length. If this value is exceeded, the meta-process will terminate, and the launched program will also be automatically stopped. Leave this value as zero if no length limits are required
For instance: incoming stream consists of dynamically sized chunks with a 7-byte header, and the length is encoded as a 32-bit number at the 3rd byte position (counting from 0). The length value includes the header size: L = 7 + len(payload)
In this case, the auto-chunking options would be as follows
You can find an example implementation in the repository , in the port
project. Use the -bin
argument to enable the demonstration of binary mode operation:
available in v310
branch of example repo