MultiThreadedIOServer
SingleThreadedIOServer
UNIXDaemon

Name:
MultiThreadedIOServer

Description:
This object performs multithreaded dispatch of IO requests. On execution it waits for a new IO request and dispatches it to a thread for processing. It then returns to dispatch another request.

This dispatching object initializes an IO object for accepting IO requests, and a logic object for handling those requests.

Options:

Overview
Option Default Values Short Description Example(s)
IOObject + A Pi3 IO object name A Pi3 object IOObject "ServerTCPIPObject"
LogicObject + A Pi3 Logic object name A Pi3 object LogicObject "HandleRequestObject"
MaxThreads + A non-negative Number of threads to use MaxThreads 10
ExitAfter -1 An integer Number of request to exit after ExitAfter 1000
- in the default indicates no default
+ in the default indicates the field is mandatory

Description of Options

IOObject
Specifies the IO object used to accept new IO requests. The IO object is created during construction. During execution of this object PIObject_copy() is invoked to create a copy IO object for each new request. When processing of the request is completed, the new IO object is destroyed and the server waits for another IO request by again calling PIObject_copy() on the main IO object. The IO object can be an object which provides an IO service (such as TCP/IP, named Pipe or shared memory IO) or an IO filter which performs translation on such an IO object (such as encryption or monitoring).
LogicObject
Specifies the logic object used to handle IO requests. The object is created during construction and its execute method invoked (using PILogic_execute()) for each IO request accepted. The IO object for the request is passed as an argument to this logic object.
MaxThreads
Specifies the maximum number of threads to use to concurrently handle IO requests. While no more threads are availablable to new IO requests will be accepted. This number should be between 1 and 1000.
ExitAfter
Specifying a positive number for this value will cause the this server object to call exit() after that number of requests. Threads with outstanding requests will be allow to complete before exit() is invoked.

This should only be used in the context of a process group where a monitor process fork()s child processes to replace ones that die. In that scenario it is good for preventing longterm memory or resource leaks.

This directive has no effect on non-UNIX systems.

Returns:
PIAPI_COMPLETED on success. PIAPI_ERROR and PIAPI_ABORT respectively for generic and severe error conditions.

Example:

	<Object>
		Name MultiThreadedIOServer
		Class MultiThreadedIOServerClass
		IOObject ServerTCPIPIO
		LogicObject HandleHTTP
	</Object>

:

Name:
SingleThreadedIOServer

Description:
This object performs single threaded dispatch of IO requests. On execution it waits for a new IO request, and completes processing of the request before accepting a new request for processing.

This dispatching object initializes an IO object for accepting IO requests, and a logic object for handling those requests.

Options:

Overview
Option Default Values Short Description Example(s)
IOObject + A Pi3 IO object name A Pi3 object IOObject "ServerTCPIPObject"
LogicObject + A Pi3 Logic object name A Pi3 object LogicObject "HandleRequestObject"
- in the default indicates no default
+ in the default indicates the field is mandatory

Description of Options

IOObject
Specifies the IO object used to accept new IO requests. The IO object is created during construction. During execution of this object PIObject_copy() is invoked to create a copy IO object for each new request. When processing of the request is completed, the new IO object is destroyed and the server waits for another IO request by again calling PIObject_copy() on the main IO object. The IO object can be an object which provides an IO service (such as TCP/IP, named Pipe or shared memory IO) or an IO filter which performs translation on such an IO object (such as encryption or monitoring).
LogicObject
Specifies the logic object used to handle IO requests. The object is created during construction and its execute method invoked (using PILogic_execute()) for each IO request accepted. The IO object for the request is passed as an argument to this logic object.

Returns:
PIAPI_COMPLETED on success. PIAPI_ERROR and PIAPI_ABORT respectively for generic and severe error conditions.

Example:

	<Object>
		Name SingleThreadedIOServer
		Class SingleThreadedIOServerClass
		IOObject ServerTCPIPIO
		LogicObject HandleHTTP
	</Object>

:

Name:
UNIXDaemon

Description:
This object performs some UNIX daemon actions, including changing the effective user and setting resource limits. This class also handles forking multiple child processes to handle requests.

Note:
On non UNIX systems execution of this object will cause the object specified with 'ServerObject' to be executed after the message specified with 'Message' is displayed. All other options and actions are ignored.

Options:

Overview
Option Default Values Short Description Example(s)
ServerObject + a Pi3 object name A Pi3 object ServerObject "ServerObject"
PIDFile - <filepath> Path to PID file PIDFile "logs/pid.log"
NumberOfProcesses 5 1..10000 Number of child processes NumberOfProcesses 10
RLimitCore - Number or 'Maximum' Limit on corefile RLimitCore 2000000
RLimitCpu - Number or 'Maximum' Limit on CPU time RLimitCPU Maximum
RLimitData - Number or 'Maximum' Limit on data segment RLimitData Maximum
RLimitFSize - Number or 'Maximum' Maximum filesize creatable RLimitFSize Maximum
User - username or #number Child process user id User jroy
Group - groupname of #number Child process group id Group #-1
LockFileName - <filename> server unique filename LockFileName "Logs/lockfile.txt"
Message - <text> Startup message Message "Welcome to OZ"
- in the default indicates no default
+ in the default indicates the field is mandatory

Description of Options

ServerObject
Specify the server object which handles requests.
PIDFile
Specifies a file to write the process identifier. This directive can be repeated multiple times to create multiple PID files. This path can be absolute or relative. If a relative path is given, the file will be created relative to the servers current directory.
NumberOfProcesses
Gives the number of child processes to generate. As child processes die, the parent monitor process will create new ones. When the parent process dies, it will kill all child processes.
RLimitCore
RLimitCPU
RLimitData
RLimitFSize
Respectively reset the soft resource limit on corefile size, CPU time, data segment size and largest creatable file for child processes of this UNIX Daemon.
User
Specifies the user that child processes will execute as. A username can be supplied or an id is assumed if the first letter is '#'
Group
Specifies the group that child processes will execute as. A groupname can be supplied an id is assumed if the first letter is '#'.
LockFileName
Specifies a file into which this class will write a temporary filename unique to this server and process group instance. The path can be absolute or relative from the current directory. This class will attempt to unlink the temporary file on exiting to this directive should not be repeated more than once.
Message
Specifies a message to be written to standard output just before the server enters its processing loop.

Returns:
PIAPI_COMPLETED on success. PIAPI_CONTINUE if no action taken. PIAPI_ERROR and PIAPI_ABORT respectively for generic and severe error conditions.

Example:

	<Object>
		Name UNIXDaemon
		Class UNIXDaemonClass
		ServerObject DefaultServerObject
		PIDFile	"Logs/pid.log"
		NumberOfProcesses 10
		RLimitCore Maximum
		RLimitCPU Maximum
		RLimitData Maximum
		RLimitFSize Maximum
		User jroy
		Group #-1
		LockFileName "Logs/lockfile.txt"
	</Object>