= Broadcast and targeted jobs =

BOINC has two mechanisms that let you control what hosts a job runs on:
'''Broadcast jobs''' and '''Targeted jobs'''.

==  Broadcast jobs ==

This mechanism lets you assign a job to ''all'' hosts, both current and future
(or to all hosts belonging to a particular user or a particular team).

This could be used to run application-specific benchmarks,
or to test for hardware or software features.

Broadcast jobs are executed exactly once on a given host.
If the job fails for any reason, it is not retried.
Broadcast jobs are not handled by a [ValidationIntro validator]
or [AssimilateIntro assimilator].
You must develop your own daemon that processes completed broadcast jobs.

To enable broadcast jobs, add
{{{
<enable_assignment_multi>1</enable_assignment_multi>
}}}
to your config.xml file.

To create a broadcast job, run
the [WorkGeneration create_work script]
with one of following optional arguments:

 --broadcast::
  broadcast the job to all hosts
 --broadcast_user ID::
  broadcast the job to all hosts of the given user
 --broadcast_team ID::
  broadcast the job to all hosts of the given team

After creating a broadcast job, you must either

 * stop and start the project, or
 * touch the file ''reread_db'' in the project directory.

The '''assign.php''' script (in ops/) lets you manage broadcast jobs.

== Targeted jobs ==

Targeted jobs are like regular jobs except that they are restricted to run on either

 * a particular host
 * hosts belonging to a particular user
 * hosts belonging to a particular team

For example, suppose your project has a group of dedicated hosts
such as a cluster or a set of cloud nodes.
You can run the BOINC client on those hosts,
attached to a particular user account.
Then, if you target a job at that user, it will run only on the dedicated hosts.

Targeted jobs are validated and assimilated like other jobs.
They are not replicated; if the job fails on one host in the set,
it will be retried on another host in the set, and so on until it completes successfully.

To enable targeted jobs, add
{{{
<enable_assignment>1</enable_assignment>
}}}
to your config.xml file.

There are two ways to target jobs.
The first is create a job that is targeted from the beginning.
To do this, run the [WorkGeneration create_work script]
with one of following optional arguments:

 --target_host ID::
  target the job to the given host
 --target_user ID::
  target the job to hosts of the given user
 --target_team ID::
  target the job to hosts of the given team

The second way is to change an existing job into a targeted job.
This might be done, for example, as part of a system that accelerates
the completion of batches of jobs by targeting the "stragglers" to dedicated hosts.

Currently this can be done only via a C++ API call,
and you can only target the job to a user.
The call is:
{{{
int restrict_wu_to_user(DB_WORKUNIT& wu, int userid);
}}}

=== Implementation notes ===

When a targeted job is created, the workunit.transitioner_flags field
is set to TRANSITION_NO_NEW_RESULTS.
This tells the transitioner to not create instances of the job;
the scheduler does that.
The transitioner does, however, check for completion and error cases.