Dicop::Data::Chunk - a chunk/piece of a Job in the Dicop (Dicop::Dicop) system.

	use Dicop::Data::Chunk;
	use Dicop qw(TOBEDONE);

	$chunk = new Dicop::Data::Chunk (
			start => 'aaa', end => 'zzz',
			job => $job, status => TOBEDONE, ); 

perl5.005, Exporter, Dicop, Dicop::Event, Dicop::Data, Math::BigInt, Math::String, Digest::MD5

Exports nothing on default.

For a description of fields a chunk has, see doc/Objects.pod.

Create a new chunk object.

	$self->merge($other_chunk);

Merge second chunk into the first one, fusing them together. Does only work if both chunks are adjacent to each other, e.g. the second one starts where the first one ends, or vice versa.

Get/set the (secret) token of the chunk.

When an chunk was issued too long ago, free it so that other clients can tackle it.

The time the chunk should linger around is taken from the client, so that some (off-line) clients can have a longer linger time than others.

Returns true when the chunk was modified (set to TOBEDONE), otherwise undef.

	if ($chunk->is_open())
	  {
	  $open_chunks++;
	  }

Returns true if the chunk is open, e.g. not DONE nor SOLVED.

Return the status code.

Return the result or undef for no result yet.

Return the first key in this chunk.

Return the last key in this chunk.

Return the size in keys/passwords from start to end.

Return the checksum.

Return the Math::String::Charset object that is used for the start and end key.

	$self->border($fixed_chars,$key,$round_up);

Correct a string to be on a border of $cnt chars. This is used to force the borders between chunks to be in a certain granularity.

For instance, if the chunk goes from 'aaa' to 'babc', the chunk end will be adjusted to 'baaa' when rounding down, or 'caaa' when rounding up (both taking three characters at the end as fixed). $round_up == 0 means rounding up, $round_up != 0 means rounding down.

Or in other words, it ensures that the given limit of keys is a multiple of the size of the border string.

	$new_chunk_status =
          $chunk->verify ($client, $result, $crc, $need_done, $need_solved);

Take a client id, chunk result (DONE, SOLVED etc), and the client-supplied CRC and try to verifiy the client's work. (This is done only when there were more than one client returning work for this chunk).

When enough verifiers for the chunk exist (in the simplest case only one), and all of them agreed on the chunk result, then we set the chunk to DONE or SOLVED, depending on the outcome.

Returns the new chunk status. Possible results are:

	DONE		enough verifiers, all said DONE (and all CRCs matched)
	SOLVED		enough verifiers, all said SOLVED (and CRCs matched)
	BAD		the result of the verifiers or their CRCs did differ
	VERIFY		not enough verifiers, but the current ones all
			agreed on result and CRC
	FAILED		chunk was issued to first client and this one FAILED
	TIMEOUT		chunk was issued to first client and this did time out

In the case of BAD, for each of the verifiers (clients), their punish() routine will be called. The status BAD must be reversed to TOBEDONE by the caller after taking appropriate action by logging or whatever needs to be done. Actually, status BAD can linger around for some hours to let the admin see the BAD chunks and the clients that caused that smell...

	my $count = $chunk->verifiers();

Returns the number of entries in the verifier list. Each client that works on this chunk will be added to this list, including his result and CRC.

	$chunk->add_verifier($client,$status,$crc);

Add an client to the list of verifiers, along with the result (SOLVED, DONE) and the crc (as returned by the client) for the chunk. Does nothing if the result is not DONE or SOLVED (e.g. it was FAILED or TIMEOUT).

	$chunk->del_verifier($client);

Remove the client from the list of verifiers. The client does not necc. to be in the list, in this case nothing will be done.

	$chunk->clear_verifiers();

Clear the list of verifiers. Done when a chunk failed verification, or was merged with another chunk.

	my $text  =  $chunk->dump_verifierlist();

Return verifierlist as text dump suitable for logging, or embedding in a mail.

	if ($chunk->client_in_verifier_list($client))
	  {
	  ...
	  }

Return true if the given client is in the list of verifiers for this chunk.

	if ($chunk->verified_by($client))
	  {
	  ...
	  }

Returns true if the client is already in the verifier list of that chunk. Used to avoid giving a chunk twice to a client.

	my $reason = $chunk->reason();

Return the error message in case the chunk was marked as FAILED.

Splice a chunk into two, the size given is either relatively (<1.0) or absolutely. Return new chunk, aka the second one of the two.

Issue a chunk to a specific client, e.g. mark it as issued and note the client ID for a later verify.

None known yet.

(c) Bundesamt fuer Sicherheit in der Informationstechnik 1998-2006

DiCoP is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

See http://www.bsi.de/ for more information.