NAME

POE::Component::Server::PreforkTCP - Perl TCP server , which can fork processes before request and each process can do with requestion corcurrently as same as Apache.

SYNOPSIS

you can use POE::Component::Server::PreforkTCP as same as POE::Component::Server::TCP, since they has same interface, but ::PreforkTCP has more parameters.

use POE;
use POE::Component::Server::PreforkTCP;

new POE::Component::Server::PreforkTCP(
	Port => 10000,
#		MaxServer => 100,
# 		MinServer => 10,
# 		StartServer => 10,
# 		...
#		MaxSessionPerServer => 1,
#		MaxServerLifeTime => 50,
#		ShutdownChildren => 1,
	ClientConnected => sub {
		my ( $heap , $input, $kernel) 
			= @_[HEAP, ARG0, KERNEL];
		$heap->{client}->put("test server , welcome$$ !\n");
		},
	ClientInput => sub {
		my ( $heap , $input, $kernel) 
			= @_[HEAP, ARG0, KERNEL];
		$heap->{client}->put("$$ : $input\n");
		print("$$ : $input\n");
		if ( $input eq 'quit' ) {
			$kernel->yield('shutdown');
		}
		if ( $input eq 'exit' ) {
			$kernel->yield('shutdown');
			$kernel->post($heap->{master_alias},
					'shutdown');
		}
		if ( $input eq 'kill' ) {
			exit 1;
		}
	}
);

POE::Kernel->run();

exit 0;

DESCRIPTION

POE::Compoent::Server::PreforkTCP based on POE, the important packages included: Wheel::SocketFactory, Wheel::Run, Component::Server::TCP... etc.

* in fact, the Component::Server::TCP is simple and easy to use,
so i keep same interface in ::PreforkTCP to ::TCP.

when a Component::Server::PreforkTCP started, it will create many the children process before any request is coming, it is called prefork and used in Apache 1 and Apache 2.

The basic process, or parent prcess, named master process , don't accept the connect request from client, the children to do the work. Master process is used to manage its children, to born, term, check if the child is expired ... etc.

Apache 1 just serve the connection by prefork, one child process serve one client in same time, Apache 2 can serve many client in one child process by creating new thread. The ::PreforkTCP can serve many client in one child in same time, too, but it needn't thread, the POE assign its power.

The ::PreforkTCP depend the package POE::Wheel::Run to spawn the child, use the package, not use fork directly, since the package can simple the code to commnicate between children and parent process, ::Wheel::Run use pipe to do it, the STDOUT of children is redirectly to parent's ::Wheel::Run obj as event arrived.

In ::PreforkTCP , the master process just recieve the children's out, and don't sent data by children's stdin, some simple instructor is sent to children by signal, USR1 to pause the server's accept, USR2 to resume the server 's accept, INT to shutdown the server.

The ::PreforkTCP support many parameters when create, they can decide how many server born, how many spare server, how long the child server life...these idea coming form apache...

Constructor parameters:

MasterAlias

MasterAlias is the master session's alias, so you can use $heap->{master_alias} to post the event to master server, it default name is 'prefork_master'.

MaxServer

MaxServer is the maxium number the master to spawn the children process, you can access it in $heap->{max_server} and change it in master server. to change it in children process is useless. it default value is 20.

StartServer

StartServer decide how many children when Prefork create. default it is 5;

MinServer

MinServer decide the minium numbers of the children process, if the children is less than it, master server will be born now children. its default value is same as StartServer.

MinSpareServer

MinSpareServer decide minium numbers of the spare children process ( no connection ). its default value is same as MinServer.

MaxSpareServer

MaxSpareServer is max spare children. its default value is MaxServer - MinServer.

NOTE: the MaxServer and MaxSpareServer is checked before MinServer and MinSpareServer.

MasterHeartBeatTime

MasterHeartBeatTime is how long the master check children's status, include children numbers, if some children has died but not cleaned...

its default value is 10 seconds, do not set its value to 0, it will occupy too much system resource.

ServerHeartBeatTime

ServerHeartBeatTime is how long the children server check its own status and report to master.

it should be faster tan MasterHeartBeatTime, its default value is half of MasterHeartBeatTime.

MaxSessionPerServer

MaxSessionPerServer is how many connection the children can accept, default is 0, means no limition. the children can accept the request as many as it can process.

in fact , the value is not very accurency, since when a limition is do in master process, so it is possible before the master send the USR1 signal to children to pause its acception, the children has accepted another connection. if the user really think it is not good, you can use ClientConnected and ClientDisconnected function to do pause and resume in children process, it is different.

it is useful there are many sync/block operater in server process, make less session the children can acception, the client will not be blocked.

even in pure POE program, the parameter can be used to limition one process's resource.

if set the value is small, you should set the bigger MaxServer for heavy server.

MaxServerExpireTime

MaxServerExpireTime is how long the children should be killed if master don't get children's heartbeat.

its default value is 5 * MasterHeartBeatTime, if the server need do with work with blocked i/, such as sync DNS request, you need give it a bigger value .

GraceExpireTime

if a child said it will exit but not exit really, how long the master should kill it.

its default value is MaxServerExpireTime.

MaxServerSpareTime

MaxServerSpareTime is how long the master should term a child if it don't accept connection in MaxServerSpareTime seconds.

it is useful if some server is blocked and can not work. but it is terrible if the server is not heavy , not too many request. so its defalut value is 0, means don't check the parameter. if you want to set the parameter, don't set it too small.

MaxServerLifeTime

MaxServerLifeTime is how long a child will be run, the master will be term it when children run too long time, maybe it is useful some server will occupy much memory in less connection, but perl will not release it, just keep the memory for furture used, but next time, maybe another children need many memory, not the one. so long long time , all children occupied many memory, maybe just one of it really need it.

its default value is 0, means don't check it.

MaxServerLifeTimes

MaxServerLifeTimes is how many connection a child can process, the master will term it after the child do the works. its goal is same as MaxServerLifeTime.

its default value is 0, means don't check it.

ShutdownChildren

the parameter is used to kill children when master exit. now the parameter can not run as same as i think, i just use it in "make test", it decided if another session can terminal the master's children.

its default value is 0, means don't kill children.

others

you can use all Component::Server::TCP's parameter to make a server work. such as, ClientInput, ClientConnected ...

NOTE:: if you use Acceptor to define yourself acceptor, maybe the prefork Server will not work correctly. since i haven't test it by a given Acceptor.

EVENTS

PreforkTCP server support some EVENTS.

shutdown

use shutdown to shutdown the connection or server as same as Server::TCP, but you should post the event to master session, and it just shutdown one children , not all server.

$kernel->post( $heap->{master_alias}, 'shutdown');

maybe it need a new event, it can shutdown all servers and master. but now no.

pause/resume

pause and resume be used to pause and resume the server's accept socket. it is master session's event in master server and children server. master server is of course is paused, don't make it accept and process connection.

heartbeat/client_manage/server_signal

don't use these event directly.

some events in master server

maybe it is useful from outside , maybe not.

back

EXPORT

None.

AUTHOR

Wang Bo <lt>wb@95700.net<gt>

SEE ALSO

perl.POE.POE::Component::Server::TCP.