camel-operation
3
CAMEL Library

# camel-operation

## Synopsis

                        CamelOperation;
    void                (*CamelOperationStatusFunc)         (struct _CamelOperation *op,
                                                             const char *what,
                                                             int pc,
                                                             void *data);
    enum                camel_operation_status_t;
    CamelOperation*     camel_operation_new                 (CamelOperationStatusFunc status,
                                                             void *status_data);
    void                camel_operation_mute                (CamelOperation *cc);
    void                camel_operation_ref                 (CamelOperation *cc);
    void                camel_operation_unref               (CamelOperation *cc);
    void                camel_operation_cancel              (CamelOperation *cc);
    void                camel_operation_uncancel            (CamelOperation *cc);
    CamelOperation*     camel_operation_register            (CamelOperation *cc);
    void                camel_operation_unregister          (CamelOperation *cc);
    void                camel_operation_cancel_block        (CamelOperation *cc);
    void                camel_operation_cancel_unblock      (CamelOperation *cc);
    int                 camel_operation_cancel_check        (CamelOperation *cc);
    int                 camel_operation_cancel_fd           (CamelOperation *cc);

## Description

## Details

### CamelOperation

    typedef struct _CamelOperation CamelOperation;

### CamelOperationStatusFunc ()

    void                (*CamelOperationStatusFunc)         (struct _CamelOperation *op,
                                                             const char *what,
                                                             int pc,
                                                             void *data);

`op` :

`what` :

`pc` :

`data` :

### enum camel_operation_status_t

    typedef enum _camel_operation_status_t {
    	CAMEL_OPERATION_START = -1,
    	CAMEL_OPERATION_END = -2,
    } camel_operation_status_t;

### camel_operation_new ()

    CamelOperation*     camel_operation_new                 (CamelOperationStatusFunc status,
                                                             void *status_data);

Create a new camel operation handle. Camel operation handles can be used in a multithreaded application (or a single operation handle can be used in a non threaded appliation) to cancel running operations and to obtain notification messages of the internal status of messages.

`status` :

  Callback for receiving status messages. This will always be called with an internal lock held.

`status_data` :

  User data.

Returns :

  A new operation handle.

### camel_operation_mute ()

    void                camel_operation_mute                (CamelOperation *cc);

mutes a camel operation permanently. from this point on you will never receive operation updates, even if more are sent.

`cc` :

### camel_operation_ref ()

    void                camel_operation_ref                 (CamelOperation *cc);

Add a reference to the CamelOperation `cc`.

`cc` :

  operation context

### camel_operation_unref ()

    void                camel_operation_unref               (CamelOperation *cc);

Unref and potentially free `cc`.

`cc` :

  operation context

### camel_operation_cancel ()

    void                camel_operation_cancel              (CamelOperation *cc);

Cancel a given operation. If `cc` is NULL then all outstanding operations are cancelled.

`cc` :

  operation context

### camel_operation_uncancel ()

    void                camel_operation_uncancel            (CamelOperation *cc);

Uncancel a cancelled operation. If `cc` is NULL then the current operation is uncancelled.

This is useful, if e.g. you need to do some cleaning up where a cancellation lying around in the same thread will abort any processing.

`cc` :

  operation context

### camel_operation_register ()

    CamelOperation*     camel_operation_register            (CamelOperation *cc);

Register a thread or the main thread for cancellation through `cc`. If `cc` is NULL, then a new cancellation is created for this thread.

All calls to `operation_register()` should save their value and call operation_register again with that, to automatically stack registrations.

`cc` :

  operation context

Returns :

  Returns the previously registered operatoin.

### camel_operation_unregister ()

    void                camel_operation_unregister          (CamelOperation *cc);

Unregister the current thread for all cancellations.

`cc` :

  operation context

### camel_operation_cancel_block ()

    void                camel_operation_cancel_block        (CamelOperation *cc);

Block cancellation for this operation. If `cc` is NULL, then the current thread is blocked.

`cc` :

  operation context

### camel_operation_cancel_unblock ()

    void                camel_operation_cancel_unblock      (CamelOperation *cc);

Unblock cancellation, when the unblock count reaches the block count, then this operation can be cancelled. If `cc` is NULL, then the current thread is unblocked.

`cc` :

  operation context

### camel_operation_cancel_check ()

    int                 camel_operation_cancel_check        (CamelOperation *cc);

Check if cancellation has been applied to `cc`. If `cc` is NULL, then the CamelOperation registered for the current thread is used.

`cc` :

  operation context

Returns :

  TRUE if the operation has been cancelled.

### camel_operation_cancel_fd ()

    int                 camel_operation_cancel_fd           (CamelOperation *cc);

Retrieve a file descriptor that can be waited on (select, or poll) for read, to asynchronously detect cancellation.

`cc` :

  operation context

Returns :

  The fd, or -1 if cancellation is not available (blocked, or has not been registered for this thread).