# cp_messages_reference

### Mechanism

The Content and Processing mechanism (CP) handles the asynchronous handover of jobs between
the enaio® server and external service instances — typically the full-text indexer, the
rendition cache and the page-count service. The jobs are kept on the server in the
[`oscpmqueue`](../database/server_cluster_and_configuration.md#database.oscpmqueue) database table; service instances pull them out,
process them and report completion back to the server.

Every job (CP message) is identified by a `MessageGUID` and assigned to a logical queue (the
`queuename` column). A service instance identifies itself to the server through a
`ServiceName` (instance ID) and pulls jobs from one or more named queues.

### Lifecycle of a message

1. **Create** — Jobs are inserted into `oscpmqueue` on the server, either explicitly through
  `std.CreateCPMessages` or via internal triggers (for example after an index data change).
  `lock_service` is initially `NULL`, so the message is unreserved.
1. **Pick up** — A service instance calls [std.GetNextCPMessage](../std.md#std.GetNextCPMessage)
  in a polling loop. The server reserves a message for that instance if one is available and
  returns `MessageGUID`, `ObjectID`, `ObjectType` and `QueueName`. An empty response
  (`MessageGUID` empty, return code still `0`) is normal and simply means no free message is
  currently waiting in the requested queues.
1. **Process** — The service instance executes the job. Typical follow-up jobs are
  [std.GetCPObjectInfo](../std.md#std.GetCPObjectInfo) for object metadata and
  [std.GetCPObjectIdxFulltext](../std.md#std.GetCPObjectIdxFulltext) for an object's
  extracted full-text content.
1. **Dispatch** — When done, the service instance reports the result back through
  [std.DispatchCPMessage](../std.md#std.DispatchCPMessage) together with a `Reason`. The
  server removes the message from the queue or keeps it for a retry, depending on the reason.
  Without a `Dispatch` call, the message remains reserved with `lock_service` set.
1. **Reset** — If a service instance aborts or restarts, it can release all reservations it
  currently holds by calling
  [std.ResetServiceCPMessages](../std.md#std.ResetServiceCPMessages). The affected jobs
  then become available again for other instances to pick up.

In addition, the rendition service reports a changed rendition back to the server through
[std.CPRenditionChanged](../std.md#std.CPRenditionChanged), which in turn may produce new
full-text messages.

### Selection and locking behaviour

Out of the unreserved messages in the requested queue, the server picks the one with the most
recent entry (`MAX(created)`) — i.e. the **newest** message first.

The reservation uses optimistic locking: `lock_service` and a freshly generated `checkguid`
are written only if the message is still unreserved at the moment of the update. The server
then reads back the `checkguid` and compares it against the value it just wrote. If they
differ — typically because a competing service instance reserved the same message at the same
time — the pickup counts as lost and the service instance receives an empty response.

### Coalescing of redundant messages

When a message is successfully picked up, the server deletes all other unreserved messages
for the same `(osid, queuename)` pair. Multiple jobs queued in quick succession for the same
object are thus automatically collapsed into a single processing step; the service instance
always works on the most recent state.

### Known queues

| Queue | Typical consumer | Purpose |
|---|---|---|
| `FULLTEXTIDX` | Full-text indexer | Register an object for full-text indexing. |
| `FULLTEXTDOC` | Full-text indexer | Index the full-text document (read the content from the full-text cache and add it to the<br>index). |
| `FULLTEXTFILTER` | Full-text indexer | Filter / pre-processing step prior to indexing. |
| `FULLTEXTLOCATION` | Full-text indexer | Location / container indexing (typical for folder objects). |
| `FULLTEXTDELETE` | Full-text indexer | Remove the index entry for a deleted object. |
| `RENDITION` | Rendition cache | Produce a rendition (e.g. PDF or text extraction) for a document. |
| `RENRESET` | Rendition cache | Reset and rebuild the rendition cache. |
| `PAGECOUNT` | Page-count service | Determine the page count of a document and store it in the index. |
> **Note:** A service instance may serve several queues simultaneously; the "queue → consumer"
mapping above reflects the typical configuration and is not enforced by the server.