Dicop::Data::Job - a job in the Dicop (Dicop::Dicop) system.

    use Dicop::Data::Job;

perl5.005, Exporter, Dicop, Dicop::Item, Math::String, Math::BigInt, Math::BigFloat

Exports nothing.

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

The chunk list contains all the chunks that make up the key/password room of the job.

Each chunk can have a status of ISSUED, DONE, TOBEDONE, SOLVED, or FAILED.

Apart from creation, there are only two events that will change the chunklist.

When a client requests a piece of work, the following things will happen:

Conversion to TOBEDONE

Any chunk that is FAILED or ISSUED for too long will be converted to TOBEDONE so that it can be issued to a client again.

Finding an appropriate sized TOBEDONE chunk

The list is then searched for a chunk that fit's the clients wish for amount of work best. If the best fitting chunk is actually more than twice what the client requested, the chunk is split into two parts, and the smaller part is taken. If the chunk is smaller, it is used nonetheless to prevent small chunks from lingering in the system indefinitely.

Thus due to a client request the chunk list may grow by zero or one chunk, which will always be of the type TOBEDONE.

The chunk the client reported back is setto SOLVED, FAILED or DONE, depending on what the client reported.

When the chunk is set to DONE, it will be tried to be merged with the chunk before and after it.

Thus returning a DONE chunk may shrink the chunk list by 0-2 chunks. Returning a FAILED or SOLVED chunk will not shrink or grow the chunk list.

The chunk list will be kept at the minimum size by this mechanism. The only way it could grow is by one client requesting lots of chunks without returning them. This is prevented by the server via a maximum number of chunks per client.

For performance reasons the reporting back of a chunk will only look at this chunk and it's two neighbours. The algorithm to find a chunk for a client will only look as far as it needs to find a suitable chunk.

A job will be closed (set to STOPPED) when one of the following occurs:

Solution found

When a solution is found, and the jobs flags don't permit it running after that (e.g. you want only one solution).

No more open chunks

When there are no more open (ISSUED, FAILED or TOBEDONE) chunks. This is only checked at the time of finding a chunk to be issued to a client.

        @files = $job->extra_files($architecture);

Return list of extra filenames necc. for this job, including files neccessary due to the jobtype this job has.

        $txt = $job->extra_fields();

If the jobtype for that job mandates extra fields, will return a text listing them in the following format:

	extra0=username,Biffy Baff
	extra1=nose,red

The strings are converted to hex like "444546,303132".

This routine is used to include them into the chunk description file.

        $txt = $job->extra_params();

If the jobtype for that job mandates extra fields, will return a text listing them in the following format:

  	username_Biffy+Baff;nose_red

This is suitable for returning them as a Dicop::Request.

	$job->flush($base_dir):

Write the chunk list of the job to the disk.

Check internal data structures like the chunklist, and in case of error, return this error. Undef for "ok".

Return the Nth chunk.

Return number of chunks with a certain status. If no argument is given, returns number if all chunks.

Returns the jobs charset as a Math::String::Charset object.

Returns true if the job is currently running, e.g. not suspended or done.

Return status code of job.

Return number of results.

Return a chunk by it's id. This does also look in the checklist, so it will always return any chunk in the job, not only the "normal" ones.

Return a chunk's index number by it's id.

	$job->report_chunk($chunk,$took);

Report a chunk back from a client, increase the results counter. Does not merge or split chunks, because the size of the chunk is needed later on.

If the chunk was in the checklist, and is finally DONE, it will be removed from the checklist.

Given a chunk number (Nth chunk in array), tries to merge the next and previous chunks with that chunk until no longer both the next and the previous chunk are DONE.

Returns number of merging operations (aka deleted chunks).

Return jobs size (aka key-room size) as Math::BigInt.

Return the percent of already done keys in this job as float with two digits after the dot. See also keys_done.

Return the number of keys still todo in this job as a big integer. See also percent_done and keys_done.

Return the number of already done keys in this job as a big integer. See also percent_done.

Given a client's speed value, try to find a suitable chunk for him. If we find a chunk that's too big, split it in two smaller pieces. The first slice will match the speed of the client.

As we walk the list, we will also convert ISSUED chunks to DONE, when they are over their age. When the job has no more chunks that are ISSUED, TOBEDONE or FAILED, it will be closed (set to DONE).

This is _HOT_ code, and executed for nearly each client request. OTOH, walking a list of 10.000 chunks takes currently less time than the final splitting of the chunk.

	my $count = $job->checklist();

Return number of chunks currently in checklist.

Clears the check list (empties it).

	$chunk->{id} = $self->new_chunk_id();

Create a new, unique ID for a new chunk.

	$job->check_also($chunk);

Makes a copy of the chunk (which contained a result), gives it a unique (for this job) ID, and adds it to the checklist.

The new chunk's status is also set to TOBEDONE, also a flag telling that this chunk is part of the checklist is set.

Returns reference to the new chunk.

	$job->checklist_del_chunk($chunk);

Delete the given chunk from the list.

Walks the checklist to find a suitable chunk for the client. The checklist is the list of chunks we need to check in addition to the normal keyspace contained in our chunklist - typically for results from other jobs.

Checks whether a given chunk (by it's id and token) is in the checklist or not. Used to decide whether a back-comming result from a client was for a chunk in the check list or inside the normal chunk list. (The IDs between the two lists are unique, so the ID alone would suffice to make the distinction, but we will later on have only the token delivered back by the client)

Restricts the chunksize to be in the range of 1..120 minutes. In addition, if max-chunk-size is set to 0, restricts the chunksize to a maximum of 5 if the job is not yet two hours old.

Converts a target file name (any file that does not end in .tgt) via an external script) to either a target hash or a target file. Sets $self-{_error}> in case anything goes wrong, or $self-{script_output}> in case the script run sucessfull.

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.