karoo::rock Class Reference

A rock is the base class for an application in the karoo project. More...

#include <rock.h>

Inherited by karoo::cave, karoo::manager, and surf.

List of all members.

Classes
class	long_hdr_reply
class	long_pkt_reply
class	long_runner
class	rock_bye
class	rock_keep_connected
Public Member Functions
	rock ()
	This creates a rock which still needs to be initialised.
	rock (const vector< text > &opts, int argc, char *argv[])
	Create a rock and initialise its command-line variables.
virtual	~rock ()
	Destroy the rock and disconnect from the system.
datagram_status	run ()
	Run the rock.
void	stop (bool block=true)
	Stop this rock cleanly.
void	refuse ()
	refuse to add any more pebbles to the output_queue
void	bye ()
	cause a ROCK_BYE_MESSAGE to be sent.
bool	isStopping () const
	Is the rock in the process of stopping?
void	add (pebble *p)
	Add a pebble to the output_queue, to be run synchronously in first-in, first-out order, along with the parsing of received datagrams, as soon as possible.
void	add (const struct timespec &ts, pebble *p)
	Add a pebble to the output_queue, to be run synchronously after a specified timestamp.
void	add (int after_seconds, pebble *p)
	Add a pebble to the output_queue, to be run synchronously after a specified delay.
int	getImminentCount (unsigned usecs=0) const
	get the number of pebbles imminent to run in the output_queue.
int	getQueueCount () const
	get the number of pebbles running or waiting in the output_queue.
exepool *	getGeneralPool ()
	Get the general_pool.
const text &	getArgument (const text &opt) const
	Get the value of a particular argument.
const text &	getArgument (const text &opt, const text &def) const
	Get the value of a particular argument.
bool	getBoolArgument (const text &opt, bool def) const
	Get the value of a particular boolean argument.
virtual void	handle (rock_datagram_message *msg)
	interpret a message and do whatever is supposed to be done as a result of receiving this message.
void	addHandler (rock_datagram_message_handler *h)
	add a handler to the array of handlers.
virtual text	getType () const
	get the type of the rock.
virtual uint8_t	getLoadFactor () const
const text &	getHost () const
	get the host name or IP address of the host that runs the rock manager
int	getPort () const
	get the port of the rock manager
int	getSelfPort () const
	get this rock's reply port where it will receive messages from other rocks and from the manager.
text	getName () const
	get the unique identifying name of this rock.
int	getAckRetry () const
	get the number of second to wait before rtrying sending a message when no ACK was received
int	getMaxRetry () const
	get the maximum number of times to retry sending a message when no ACK is received, before giving up
size_t	getMessageSize () const
	get the default message size for the buffer when receiving datagrams
log	getLogger () const
	get a copy of the rock's logger
enum log_level	getLoggerLevel () const
	check the level of the logger
virtual rock_datagram_message *	createMessage (uint32_t msg_type, text recipient_host=null_string, int recipient_port=0, size_t message_size=0)
	Create a rock_datagram_message.
virtual rock_datagram_message *	createRockHelloMessage ()
	Create a ROCK_HELLO_MESSAGE to the manager.
virtual rock_datagram_message *	createRockPingMessage ()
	Create a ROCK_PING_MESSAGE to the manager.
void	startKeepConnectedHello (time_t poll_secs=5, time_t initial_delay=0)
	Start a keep-connected process.
void	sendMessageByAddress (rock_datagram_message *msg)
	Send a message without using the recipient_name.
void	sendMessage (rock_datagram_message *msg)
	Send a message.
bool	sendMessageByType (rock_datagram_message *msg, const text &type)
	Send a message to the best recipient found of the specified rock type.
void	doHello (const text &name, const text &type, const text &host, int port)
	Do the setup of the children map that is necessary when a ROCK_HELLO_MESSAGE is received.
void	doPing (const text &name, const text &host, int port, bool create=false)
	Validate the children map's entry for a rock when any message is received.
void	doPing (const text &name, const text &type, const text &host, int port, uint8_t load_factor)
	Validate the children map's entry for a rock which sent a ROCK_PING_MESSAGE.
void	doBye (const text &name)
	Remove a rock's entry from the children map when a ROCK_BYE_MESSAGE is received.
void	doLongHeader (const text &name, const text &host, int port, uint32_t long_size, uint32_t num_packets, rock_datagram_message *msg, uint64_t seq)
	Set up the long message header.
bool	doLongPacket (const text &name, const text &host, int port, uint64_t hdr_seq, uint32_t pkt_num, uint32_t this_size, unsigned char *data)
	Process a packet which is part of a long message.
void	notifyAcked (uint64_t seq, rock_datagram_message *msg)
	notify the rock that a previously sent message has been acknowledged.
uint64_t	getSequence ()
	get the next available message sequence number
bool	getRemoteRockType (const text &name, text &type) const
	Get the type of a named remote rock.
Protected Member Functions
void	getArguments (const vector< text > &opts, int argc, char *argv[])
	gets the command-line arguments and sets up the args array.
virtual datagram_status	create_client ()
	create the datagram_client object.
virtual datagram_status	create_server ()
	create the datagram_server object.
virtual datagram_status	init ()
	Initilise everything except for the server.
remote_rock *	findRockByType (const text &type)
	Find a rock by type name.
bool	syncChildren (map< text, remote_rock * > &rocks, vector< remote_rock * > &rocks_arr)
	Sync the rocks that are managed, with the list supplied.
Protected Attributes
log	logger
	This is the logger which is used for any logging of error messages and debugs etc.
Friends
void	rock_datagram_message_ack::run ()
void	rock_datagram_message_handler::sendAck (rock_datagram_message *reply)
void	message_handler_runner::run ()
	this handler is used to create pebbles that are run in the general_pool to handle the guts of the standard messages

---

Detailed Description

A rock is the base class for an application in the karoo project.

---

Constructor & Destructor Documentation

karoo::rock::rock

(

)

This creates a rock which still needs to be initialised.

Its only included here in case a child class wants to do the initialisation of arguments and parameters, after doing some other initialisation.

karoo::rock::rock	(	const vector< text > &	opts,
		int	argc,
		char *	argv[]
	)

Create a rock and initialise its command-line variables.

You must pass it an array of variable names (opts) that it will parse from the command line arguments (argv). There are some arguments that it will always handle even if you don't specify them:

• "name", the name of the rock,
• "host" the hostname of the manager
• "port" the port of the manager, defaults to 7919 (the 1000th prime number)
• self-port the port this rock is listening to.
• ack-retry the number of seconds to wait before checking if a message was acked, and if not, to resend
• log-level the level of logging output: DEBUG, INFO, WARING, ERROR, FATAL
• "message-size" the maximum message size to be received, defaults to 1024.
• "pool-size" the pool size for execution of application logic, defaults to 3
• "kill-pid" the pid of an instance of itself that should first be killed

Parameters:

	opts	an array of names of arguments that this executable will handle.
	argc	the number of arguments passed into main() from the shell.
	argv	an array of strings passed into main() from the shell.

Exceptions:

text

if there was a problem

virtual karoo::rock::~rock

(

)

[virtual]

Destroy the rock and disconnect from the system.

Note that it is important to call rock::stop(true) before calling the destructor, otherwise race conditions will arrise from queues that are still running and pebbles in the queues that reference the rock.

---

Member Function Documentation

void karoo::rock::add	(	int	after_seconds,
		pebble *	p
	)

Add a pebble to the output_queue, to be run synchronously after a specified delay.

This is a convenience function that sets up the timestamp for you.

Parameters:

	p	the pebble that must be run.
	after_seconds	the number of seconds after which this pebble should be run. Note that you must not add slow pebbles to this queue. Rather use the general_pool for that.

See also:

getGeneralPool()

void karoo::rock::add	(	const struct timespec &	ts,
		pebble *	p
	)

Add a pebble to the output_queue, to be run synchronously after a specified timestamp.

Parameters:

	p	the pebble that must be run.
	ts	the time when the pebble should be run. Note that you must not add slow pebbles to this queue. Rather use the general_pool for that.

See also:

getGeneralPool()

void karoo::rock::add

(

pebble *

p

)

Add a pebble to the output_queue, to be run synchronously in first-in, first-out order, along with the parsing of received datagrams, as soon as possible.

Parameters:

p

the pebble that must be run. Note that you must not add slow pebbles to this queue. Rather use the general_pool for that.

void karoo::rock::addHandler

(

rock_datagram_message_handler *

h

)

add a handler to the array of handlers.

The rock will iterate through the array of handlers, passing each incoming message to each handler in turn until one of them returns TRUE to indicate that the message was handled. Note that calling this method will cause the reference count of the handler to be incremented, and when the rock is destroyed, the reference count will be decremented, resulting in the handler being destroyed.

void karoo::rock::bye

(

)

cause a ROCK_BYE_MESSAGE to be sent.

Eventually when its ACK is received, and when the output_queue has cleared, or when 7 or more seconds have elapsed, this rock's stop() method will be called.

virtual datagram_status karoo::rock::create_client

(

)

[protected, virtual]

create the datagram_client object.

All of the parameters will be set up from the command-line arguments.

Returns:

the status of the datagram_client after it is created. This should be DATAGRAM_OK. Note this is called by init().

virtual datagram_status karoo::rock::create_server

(

)

[protected, virtual]

create the datagram_server object.

All of the parameters will be set up from the command-line arguments.

Returns:

the status of the datagram_server after it is created. This should be DATAGRAM_OK. Note that this method is called by the run() method, which also calls the run_queue->start() method so that it takes over the caller thread... I.e. it does not return until after the stop() method is called, unless there was an error in creating the server.

virtual rock_datagram_message* karoo::rock::createMessage	(	uint32_t	msg_type,
		text	recipient_host = null_string,
		int	recipient_port = 0,
		size_t	message_size = 0
	)			[virtual]

Create a rock_datagram_message.

Returns:

the message (already completed with all header information contained in it)

Exceptions:

bad_address

if the address is invalid

Parameters:

	recipient	the IP address or host name of the recipient, defaults to manager's host
	recipient_port	the port of the recipient, defaults to manager's port if non-zero, then set the message up to this size rather than the default

virtual rock_datagram_message* karoo::rock::createRockHelloMessage

(

)

[virtual]

Create a ROCK_HELLO_MESSAGE to the manager.

Returns:

the message (already completed with all information contained in it)

Exceptions:

bad_address

if the address is invalid

virtual rock_datagram_message* karoo::rock::createRockPingMessage

(

)

[virtual]

Create a ROCK_PING_MESSAGE to the manager.

Returns:

the message (already completed with all information contained in it)

Exceptions:

bad_address

if the address is invalid

void karoo::rock::doBye

(

const text &

name

)

Remove a rock's entry from the children map when a ROCK_BYE_MESSAGE is received.

Parameters:

name

the unique name of the remote rock.

void karoo::rock::doHello	(	const text &	name,
		const text &	type,
		const text &	host,
		int	port
	)

Do the setup of the children map that is necessary when a ROCK_HELLO_MESSAGE is received.

Parameters:

	name	the unique name of the remote rock.
	type	the type of the remote rock.
	host	the host name that the remote rock is running on.
	port	the port number that the remote rock is receiving datagrams on.

void karoo::rock::doLongHeader	(	const text &	name,
		const text &	host,
		int	port,
		uint32_t	long_size,
		uint32_t	num_packets,
		rock_datagram_message *	msg,
		uint64_t	seq
	)

Set up the long message header.

Parameters:

	name	the unique name of the remote rock.
	host	the host name that the remote rock is running on.
	port	the port number that the remote rock is receiving datagrams on.
	long_size	the total size of the long message.
	num_packets	the number of packets it will be sent in.
	msg	the actual message sent from the remote rock, containing the header.
	seq	the sequence number of the message sent from the remote rock, containing the header.

bool karoo::rock::doLongPacket	(	const text &	name,
		const text &	host,
		int	port,
		uint64_t	hdr_seq,
		uint32_t	pkt_num,
		uint32_t	this_size,
		unsigned char *	data
	)

Process a packet which is part of a long message.

Parameters:

	name	the unique name of the remote rock.
	host	the host name that the remote rock is running on.
	port	the port number that the remote rock is receiving datagrams on.
	hdr_seq	the sequence number of the (previously received) header message.
	pkt_num	the packet number of this packet (e.g. if 3 packets are neede to send the message, packet number may be 0,1, or 2).
	this_size	the size of the data in this packet (size of the data parameter in bytes).
	data	the ddata for this packet. Note that the caller does not need to free the memory in data.

void karoo::rock::doPing	(	const text &	name,
		const text &	type,
		const text &	host,
		int	port,
		uint8_t	load_factor
	)

Validate the children map's entry for a rock which sent a ROCK_PING_MESSAGE.

Parameters:

	name	the unique name of the remote rock.
	type	the type of the remote rock.
	host	the host name that the remote rock is running on.
	port	the port number that the remote rock is receiving datagrams on.
	load_factor	the current load experienced by the sending rock (0 = no load, 0xff = most loaded)

void karoo::rock::doPing	(	const text &	name,
		const text &	host,
		int	port,
		bool	create = false
	)

Validate the children map's entry for a rock when any message is received.

Parameters:

	name	the unique name of the remote rock.
	host	the host name that the remote rock is running on.
	port	the port number that the remote rock is receiving datagrams on.

remote_rock* karoo::rock::findRockByType

(

const text &

type

)

[protected]

Find a rock by type name.

There may be many rocks of the same type, this will return the best instance for sending a message to. I.e. a rock that is valid and not overly loaded. Note that this method must be called synchronously using children_sem.

Parameters:

type

the required type name of the rock

Returns:

the unique rock description, else a NULL if it was not found.

const text& karoo::rock::getArgument	(	const text &	opt,
		const text &	def
	)			const

Get the value of a particular argument.

Parameters:

	opt	the name of the command-line argument.
	def	the default value to return if that argument was not specified on the command-line.

Returns:

the value of that argument

const text& karoo::rock::getArgument

(

const text &

opt

)

const

Get the value of a particular argument.

Parameters:

opt

the name of the command-line argument.

Returns:

the value of that argument

void karoo::rock::getArguments	(	const vector< text > &	opts,
		int	argc,
		char *	argv[]
	)			[protected]

gets the command-line arguments and sets up the args array.

This is called by the constructor.

bool karoo::rock::getBoolArgument	(	const text &	opt,
		bool	def
	)			const

Get the value of a particular boolean argument.

Parameters:

	opt	the name of the command-line argument.
	def	the default value to return if that argument was not specified on the command-line.

Returns:

the value of that argument

int karoo::rock::getImminentCount

(

unsigned

usecs = 0

)

const

get the number of pebbles imminent to run in the output_queue.

Note this does not count the number of imminent application pebbles in the general_pool.

Parameters:

usecs

the number of microseconds (of waiting pebbles) to consider as "imminent" Note that you must not add slow pebbles to this queue. Rather use the general_pool for that.

See also:

getGeneralPool()

text karoo::rock::getName

(

)

const [inline]

get the unique identifying name of this rock.

int karoo::rock::getQueueCount

(

)

const

get the number of pebbles running or waiting in the output_queue.

Note this does not count the number of application pebbles in the general_pool.

bool karoo::rock::getRemoteRockType	(	const text &	name,
		text &	type
	)			const

Get the type of a named remote rock.

Parameters:

	name	the name ofthe remote rock to look up.
	type	the type of the remote rock will be written into this text reference.

Returns:

true if the named remote rock was found.

int karoo::rock::getSelfPort

(

)

const [inline]

get this rock's reply port where it will receive messages from other rocks and from the manager.

virtual text karoo::rock::getType

(

)

const [inline, virtual]

get the type of the rock.

This must be implemented for your class which inherits from rock, so that instead of returning "rock" (as this one does), it will return a type name that describes the class.

virtual void karoo::rock::handle

(

rock_datagram_message *

msg

)

[virtual]

interpret a message and do whatever is supposed to be done as a result of receiving this message.

Note that this method is only ever intended to be called from the datagram_message::run() method. It should not be slow to execute. If it is likely to be slow, then you must rather create another pebble to run that (slow) task and run it in another queue. Otherwise, the output_queue (which is intended to only execute methods that return quickly) will become a bottleneck and cause latency in the handling of messages.

virtual datagram_status karoo::rock::init

(

)

[protected, virtual]

Initilise everything except for the server.

This calls create_client() and returns the status of the client, which should be DATAGRAM_OK if all is well.

bool karoo::rock::isStopping

(

)

const

Is the rock in the process of stopping?

Returns:

true if the bye() method has been called.

void karoo::rock::notifyAcked	(	uint64_t	seq,
		rock_datagram_message *	msg
	)

notify the rock that a previously sent message has been acknowledged.

Parameters:

	seq	the sequence number of the ACKed message.
	msg	the ACK message itself. Its possible that the ACK message has extra data in it for reply. The read pos will be reset to zero.

datagram_status karoo::rock::run

(

)

Run the rock.

This will not return until the rock is exited.

Returns:

DATAGRAM_OK if all is OK, else connect error.

void karoo::rock::sendMessage

(

rock_datagram_message *

msg

)

Send a message.

Parameters:

msg

the message to send (which must have recipient name set, or the recipient IP and port.)

Exceptions:

	rock_exception_read	if there is any error in reading the information before sending.
	bad_address	if the address specified indirectly by the recipient name, is invalid Note that the message object will be destroyed by the rock once it's sent.

void karoo::rock::sendMessageByAddress

(

rock_datagram_message *

msg

)

Send a message without using the recipient_name.

Use the host and port in the message.

Parameters:

msg

the message to send (which must have recipient IP and port set.)

Exceptions:

	rock_exception_read	if there is any error in reading the information before sending.
	bad_address	if the address specified indirectly by the recipient name, is invalid Note that the message object will be destroyed by the rock once it was sent.

bool karoo::rock::sendMessageByType	(	rock_datagram_message *	msg,
		const text &	type
	)

Send a message to the best recipient found of the specified rock type.

Parameters:

	msg	the message to send (which must have recipient name set, or the recipient IP and port.)
	type	the rock type to send to.

Returns:

true for success, false if there were no matching rocks found.

Exceptions:

	rock_exception_read	if there is any error in reading the information before sending.
	bad_address	if the address specified indirectly by the recipient name, is invalid Note that the message object will be destroyed by the rock once it's sent.

void karoo::rock::startKeepConnectedHello	(	time_t	poll_secs = 5,
		time_t	initial_delay = 0
	)

Start a keep-connected process.

This sends a ROCK_HELLO_MESSAGE to the manager periodically. If the manager has been restarted, then this will re-connect.

Parameters:

	poll_secs	the delay between polls
	initial_delay	the delay before sending the first HELLO message.

Exceptions:

bad_address

if the address is invalid

void karoo::rock::stop

(

bool

block = true

)

Stop this rock cleanly.

This causes the application to tidy up and exit.

bool karoo::rock::syncChildren	(	map< text, remote_rock * > &	rocks,
		vector< remote_rock * > &	rocks_arr
	)			[protected]

Sync the rocks that are managed, with the list supplied.

This will first send KILL messages to all the rocks that are different or not existing in the suplied list. The correct way to call this is to keep calling it, from a deleyed pebble, until it returns true. The first few times you call it, it will probably return false. This is because it will first try to kill the children that don't match, and they of course won't die immediately. This method should not be colled more frequently than once every 5 seconds.

Parameters:

	rocks	the list of rocks that you want to be managed by this server, indexed by name.
	rocks_arr	the list of rocks that you want to be managed by this server, in order of startup.

Returns:

true for succes, false if anything did not quite work. Diagnostics will be written to this rock's log.

---

Member Data Documentation

log karoo::rock::logger [protected]

This is the logger which is used for any logging of error messages and debugs etc.

Referenced by getLogger(), and getLoggerLevel().

---

The documentation for this class was generated from the following file:

• rock/rock.h