Trait plumber_rs::servlet::AsyncServlet[−][src]

pub trait AsyncServlet {
    type AsyncTaskData: Sized;
    fn init(
        &mut self, 
        args: &[&str], 
        type_model: TypeModelObject
    ) -> ServletFuncResult;

    fn async_init(
        &mut self, 
        handle: &AsyncTaskHandle
    ) -> Option<Box<Self::AsyncTaskData>>;

    fn async_exec(
        handle: &AsyncTaskHandle, 
        task_data: &mut Self::AsyncTaskData
    ) -> ServletFuncResult;

    fn async_cleanup(
        &mut self, 
        handle: &AsyncTaskHandle, 
        task_data: &mut Self::AsyncTaskData
    ) -> ServletFuncResult;

    fn cleanup(&mut self) -> ServletFuncResult;
}

The trait for an asynchronous servlet.

An async servlet is a servlet that uses an async thread to run. It's also possible the async servlet uses some event driven model such as ASIO. This model is useful when the servlet isn't CPU bound and this will makes the task yield the worker thread to other event.

Associated Types

The private data buffer used by the async buffer.

A private data buffer for this async task is the data object that contains all the information async_exec would use and doesn't share to anyone else.

So this per task isolation eliminates the race condition of an async task.

See the async servlet programming model documentation for details

Required Methods

The initialization function.

This should be called by the Plumber framework before the application gets started. All the pipe declaration should be done in this function.

  • args: The servlet init argument list
  • type_model: The type model object

Return the result of the servlet

Initialize the async task.

This function will be called by the Plumber framework from any worker thread. The servlet should allocate the private data object which would be used for this task only.

  • handle The async handle for this task

Return The newly created async task private data, None indicates failure

Run the execution task.

This function will be called by Plumber framework from any async processing thread. In this function, all the Plumber API beside the async handle related ones are disabled and will return an error when it gets called.

This is desgined for the slow operation such as network IO, database query, etc.

The task result should be put into task private data, so that the async_cleanup function can consume it.

  • handle: The async task handle
  • task_data: The private task data

Returns the servlet function invocation result

The finalization step of an async task.

In this step, the async task execution result should have been propageated by the async_exec thread already. And this function is responsible to write the slow operation result to the pipe as well as some task cleanup.

This function will be called by Plumber framework from the same worker thread as async_init. So all the Plumber API can be used in the execution stage can be used at this point.

  • handle: The async task handle
  • task_data: The async task private data

Return the servlet function invocation result

The cleanup function

This should be called by Plumber framework when the Plumber application gets either killed or upgraded (and new version of the binary is loaded).

Return the servlet function result.

Implementors