Main Content

backgroundPool

Environment for running code in the background

    Description

    Use the background pool to run code in the background. When you run code in the background, you can run other code in your MATLAB® session at the same time.

    Creation

    Description

    example

    p = backgroundPool returns the background pool.

    Properties

    expand all

    This property is read-only.

    Queue of FevalFuture objects to run on the background pool, specified as an FevalQueue object. You can use this property to check the pending and running future variables of the parallel pool. To create future variables, use parfeval (Parallel Computing Toolbox) and parfevalOnAll (Parallel Computing Toolbox). For more information on future variables, see Future.

    Data Types: FevalQueue

    This property is read-only.

    Number of workers, specified as a positive integer scalar.

    • If you do not have Parallel Computing Toolbox™, the value is 1.

    • If you have the Parallel Computing Toolbox, NumWorkers is equal to the number of physical cores you have. For example, if you run MATLAB on a machine with four physical cores, the value is 4. You can reduce this value using maxNumCompThreads before first usage of backgroundPool.

    This property is read-only.

    Flag that indicates whether the background pool is busy, specified as true or false. The pool is busy if there is outstanding work for the pool to complete.

    Object Functions

    parfevalRun function in background
    parfevalOnAll (Parallel Computing Toolbox)Execute function asynchronously on all workers in parallel pool

    Examples

    collapse all

    This example shows how to run a function in the background using parfeval and backgroundPool. When you run a function in the background, you can run other MATLAB® code at the same time.

    Use parfeval to run the function magic(3) and retrieve one output. Specify backgroundPool as the first argument to run the function in the background. When you use parfeval, you create a Future object.

    f = parfeval(backgroundPool,@magic,1,3);

    To retrieve the output from the background, use fetchOutputs. MATLAB returns the output once the execution of magic is complete.

    fetchOutputs(f)
    ans = 3×3
    
         8     1     6
         3     5     7
         4     9     2
    
    

    This example shows how to read images from an Amazon® S3 bucket in the background.

    Use an image datastore to connect to your bucket. For more information on how to set up access to your S3 bucket, see Work with Remote Data.

    Replace "s3://MyBucket/data" with a URL to a data folder in your S3 bucket.

    ds = imageDatastore("s3://MyBucket/data");

    Use parfeval to read data from the S3 bucket. Specify backgroundPool as the first argument to run the function in the background. Then, read all of the data from the datastore.

    f = parfeval(backgroundPool,@readall,1,ds);

    You can run other functions while you download the data from the S3 bucket. To retrieve all of the images from the background, use fetchOutputs. MATLAB returns the output once the execution of readall is complete.

    T = fetchOutputs(f);
    imout = imtile(T);
    imshow(imout)

    Limitations

    • Pools created using parpool(‘threads’) and backgroundPool are both thread-based pools which utilize the same resources. It is possible that activity on one pool may block activity on the other and vice versa. Additionally, persistent data and random number generation stream state are shared in between these pools. For more information on controlling random number streams, see Control Random Number Streams on Workers (Parallel Computing Toolbox).

    Version History

    Introduced in R2021b