/* Copyright (C) 2001-2026 Artifex Software, Inc.

   All Rights Reserved.

   This software is provided AS-IS with no warranty, either express or

   implied.

   This software is distributed under license and may not be copied,

   modified or distributed except as expressly authorized under the terms

   of the license contained in the file LICENSE in this distribution.

   Refer to licensing information at http://www.artifex.com or contact

   Artifex Software, Inc.,  39 Mesa Street, Suite 108A, San Francisco,

   CA 94129, USA, for further information.

*/

/* Command list - Support for multiple rendering threads */

#include "memory_.h"

#include "gx.h"

#include "gp.h"

#include "gpcheck.h"

#include "gxsync.h"

#include "gserrors.h"

#include "gxdevice.h"

#include "gsdevice.h"

#include "gxdevmem.h"           /* must precede gxcldev.h */

#include "gdevprn.h"            /* must precede gxcldev.h */

#include "gxcldev.h"

#include "gxgetbit.h"

#include "gdevplnx.h"

#include "gdevppla.h"

#include "gsmemory.h"

#include "gsmchunk.h"

#include "gxclthrd.h"

#include "gdevdevn.h"

#include "gsicc_cache.h"

#include "gsicc_manage.h"

#include "gstrans.h"

#include "gzht.h"   /* for gx_ht_cache_default_bits_size */

/* Forward reference prototypes */

static int clist_start_render_thread(gx_device *dev, int thread_index, int band);

static void clist_render_thread(void* param);

static void clist_render_thread_no_output_fn(void* param);

/*

        Notes on operation:

        We now have 2 mechanisms for rendering threads.

        Both mechanisms use a process_page procedure set to

        clist_process_page_mt so control arrives here to render the page

        for output.

        The interpreter calls the devices print_page function. Devices

        then call process_page with an options structure that inclues

        both a process_fn and an output_fn.

        In all cases that we care about here, process_page is set to

        clist_process_page_mt. For both mechanisms, this function sets

        up a pool of n worker threads all ready to render different

        bands of the file.

        This function then causes each worker to render a thread in

        turn (by calling process_fn, which calls back to getbits, which

        causes the band to be rendered to a buffer).

        Most devices that are just writing each band to an output file

        rely on 'in-order' calling. That is to say, they need to output

        the data from band 0, followed by that from band 1, etc. (or

        possibly band n-1, followed by band-2, etc).

        Such devices define an 'output_fn', which is called back with

        the results of each band in turn. We guarantee that this

        output_fn is called in the order it expects.

        The only downside to this way of working, is that threads can

        be sat around not working for long periods - especially if the

        different bands take different lengths of time to render.

        For example, imagine if we are running with 4 workers. We

        kick off rendering for band 0,1,2,3 at the same time. Whichever

        order those renderings finish in, we can only ever output them

        in the order 0,1,2,3.

        This means that if band 3 finishes early (perhaps its contents

        are less complex than the other bands), it will be sat there

        idle waiting for all the other bands to finish before it can

        output, and resume its next rendering.

        For devices that are not dependent on the order in which data

        becomes available, we therefore offer a second mechanism; by

        setting output_fn to NULL, we indicate that process_fn will

        not only render the page, it will 'output' it too, and handle

        the selection of which band to render next.

        In this mode, the render threads can always be kept busy,

        modulo any blocking that happens within the process_fn. For

        devices which can operate in this way, non-trivial speedups

        can be given.

*/

/* clone a device and set params and its chunk memory                   */

/* The chunk_base_mem MUST be thread safe                               */

/* Return NULL on error, or the cloned device with the dev->memory set  */

/* to the chunk allocator.                                              */

/* Exported for use by background printing.                             */

gx_device *

setup_device_and_mem_for_thread(gs_memory_t *chunk_base_mem, gx_device *dev, bool bg_print, gsicc_link_cache_t **cachep)

{

    int i, code;

    char fmode[4];

    gs_memory_t *thread_mem;

    gx_device_clist *cldev = (gx_device_clist *)dev;

    gx_device_printer *pdev = (gx_device_printer *)dev;

    gx_device_clist_common *cdev = (gx_device_clist_common *)cldev;

    gx_device *ndev;

    gx_device_clist *ncldev;

    gx_device_clist_common *ncdev;

    gx_device_printer *npdev;

    gx_device *protodev;

    gs_c_param_list paramlist;

    gs_devn_params *pclist_devn_params;

    gx_device_buf_space_t buf_space;

    size_t min_buffer_space;

    /* Every thread will have a 'chunk allocator' to reduce the interaction

     * with the 'base' allocator which has 'mutex' (locking) protection.

     * This improves performance of the threads.

     */

    if ((code = gs_memory_chunk_wrap(&(thread_mem), chunk_base_mem )) < 0) {

        emprintf1(dev->memory, "chunk_wrap returned error code: %d\n", code);

        return NULL;

    }

    /* Find the prototype for this device (needed so we can copy from it) */

    for (i=0; (protodev = (gx_device *)gs_getdevice(i)) != NULL; i++)

        if (strcmp(protodev->dname, dev->dname) == 0)

            break;

    /* Clone the device from the prototype device */

    if (protodev == NULL ||

        (code = gs_copydevice((gx_device **) &ndev, protodev, thread_mem)) < 0 ||

        ndev == NULL) {       /* should only happen if copydevice failed */

        gs_memory_chunk_release(thread_mem);

        return NULL;

    }

    ncldev = (gx_device_clist *)ndev;

    ncdev = (gx_device_clist_common *)ndev;

    npdev = (gx_device_printer *)ndev;

    gx_device_fill_in_procs(ndev);

    ((gx_device_printer *)ncdev)->buffer_memory =

        ncdev->memory =

            ncdev->bandlist_memory =

               thread_mem;

    ndev->PageCount = dev->PageCount;       /* copy to prevent mismatch error */

    npdev->file = pdev->file;               /* For background printing when doing N copies with %d */

    strcpy((npdev->fname), (pdev->fname));

    ndev->color_info = dev->color_info;     /* copy before putdeviceparams */

    ndev->pad = dev->pad;

    ndev->log2_align_mod = dev->log2_align_mod;

    ndev->num_planar_planes = dev->num_planar_planes;

    ndev->icc_struct = NULL;

    /* If the device ICC profile (or proof) is OI_PROFILE, then that was not handled

     * by put/get params, and we cannot share the profiles between the 'parent' output device

     * and the devices created for each thread. Thus we also cannot share the icc_struct.

     * In this case we need to create a new icc_struct and clone the profiles.  The clone

     * operation also initializes some of the required data

     * We need to do this *before* the gs_getdeviceparams/gs_putdeviceparams so gs_putdeviceparams

     * will spot the same profile being used, and treat it as a no-op. Otherwise it will try to find

     * a profile with the 'special' name "OI_PROFILE" and throw an error.

     */

#define DEV_PROFILE_IS(DEV, PROFILE, MATCH) \

    ((DEV)->icc_struct != NULL &&\

     (DEV)->icc_struct->PROFILE != NULL &&\

     strcmp((DEV)->icc_struct->PROFILE->name, MATCH) == 0)

    if (bg_print ||

        !gscms_is_threadsafe() ||

        DEV_PROFILE_IS(dev, device_profile[GS_DEFAULT_DEVICE_PROFILE], OI_PROFILE) ||

        DEV_PROFILE_IS(dev, proof_profile, OI_PROFILE)) {

        ndev->icc_struct = gsicc_new_device_profile_array(ndev);

        if (!ndev->icc_struct) {

            emprintf1(ndev->memory,

                  "Error setting up device profile array, code=%d. Rendering threads not started.\n",

                  code);

            goto out_cleanup;

        }

        if ((code = gsicc_clone_profile(dev->icc_struct->device_profile[GS_DEFAULT_DEVICE_PROFILE],

            &(ndev->icc_struct->device_profile[GS_DEFAULT_DEVICE_PROFILE]), ndev->memory)) < 0) {

            emprintf1(dev->memory,

                "Error setting up device profile, code=%d. Rendering threads not started.\n",

                code);

            goto out_cleanup;

        }

        if (dev->icc_struct->proof_profile &&

           (code = gsicc_clone_profile(dev->icc_struct->proof_profile,

            &ndev->icc_struct->proof_profile, ndev->memory)) < 0) {

            emprintf1(dev->memory,

                "Error setting up proof profile, code=%d. Rendering threads not started.\n",

                code);

            goto out_cleanup;

        }

    }

    else {

        /* safe to share the icc_struct among threads */

        ndev->icc_struct = dev->icc_struct;  /* Set before put params */

        rc_increment(ndev->icc_struct);

    }

    /* get the current device parameters to put into the cloned device */

    gs_c_param_list_write(&paramlist, thread_mem);

    if ((code = gs_getdeviceparams(dev, (gs_param_list *)&paramlist)) < 0) {

        emprintf1(dev->memory,

                  "Error getting device params, code=%d. Rendering threads not started.\n",

                  code);

        goto out_cleanup;

    }

    gs_c_param_list_read(&paramlist);

    if ((code = gs_putdeviceparams(ndev, (gs_param_list *)&paramlist)) < 0)

        goto out_cleanup;

    gs_c_param_list_release(&paramlist);

    /* In the case of a separation device, we need to make sure we get the

       devn params copied over */

    pclist_devn_params = dev_proc(dev, ret_devn_params)(dev);

    if (pclist_devn_params != NULL) {

        code = devn_copy_params(dev, ndev);

        if (code < 0) {

#ifdef DEBUG /* suppress a warning on a release build */

            (void)gs_note_error(gs_error_VMerror);

#endif

            goto out_cleanup;

        }

    }

    /* Also make sure supports_devn is set correctly */

    ndev->icc_struct->supports_devn = cdev->icc_struct->supports_devn;

    ncdev->page_uses_transparency = cdev->page_uses_transparency;

    if_debug3m(gs_debug_flag_icc, cdev->memory,

               "[icc] MT clist device = "PRI_INTPTR" profile = "PRI_INTPTR" handle = "PRI_INTPTR"\n",

               (intptr_t)ncdev,

               (intptr_t)ncdev->icc_struct->device_profile[GS_DEFAULT_DEVICE_PROFILE],

               (intptr_t)ncdev->icc_struct->device_profile[GS_DEFAULT_DEVICE_PROFILE]->profile_handle);

    /* If the device is_planar, then set the flag in the new_device and the procs */

    if ((ncdev->num_planar_planes = cdev->num_planar_planes))

        gdev_prn_set_procs_planar(ndev);

    /* Make sure that the ncdev BandHeight matches what we used when writing the clist, but

     * re-calculate the BandBufferSpace so we don't over-allocate (in case the page uses

     * transparency so that the BandHeight was reduced.)

     */

    ncdev->space_params.band = cdev->page_info.band_params;

    ncdev->space_params.banding_type = BandingAlways;

    code = npdev->printer_procs.buf_procs.size_buf_device

                (&buf_space, (gx_device *)ncdev, NULL, ncdev->space_params.band.BandHeight, false);

    min_buffer_space = clist_minimum_buffer(cdev->nbands);

    ncdev->space_params.band.BandBufferSpace = buf_space.bits + buf_space.line_ptrs;

    /* Check if the BandBufferSpace is large enough to allow us for clist writing */

    /* to prevent an error from gdev_prn_allocate_memory which checks that.       */

    if (min_buffer_space > ncdev->space_params.band.BandBufferSpace)

        ncdev->space_params.band.BandBufferSpace = min_buffer_space;

    ncdev->space_params.band.tile_cache_size = cdev->page_info.tile_cache_size; /* must be the same */

    ncdev->space_params.band.BandBufferSpace += cdev->page_info.tile_cache_size;

    /* gdev_prn_allocate_memory sets the clist for writing, creating new files.

     * We need  to unlink those files and open the main thread's files, then

     * reset the clist state for reading/rendering

     */

    if ((code = gdev_prn_allocate_memory(ndev, NULL, ndev->width, ndev->height)) < 0)

        goto out_cleanup;

    if (ncdev->page_info.tile_cache_size != cdev->page_info.tile_cache_size) {

        emprintf2(thread_mem,

                   "clist_setup_render_threads: tile_cache_size mismatch. New size=%"PRIdSIZE", should be %"PRIdSIZE"\n",

                   ncdev->page_info.tile_cache_size, cdev->page_info.tile_cache_size);

        goto out_cleanup;

    }

    /* close and unlink the temp files just created */

    ncdev->page_info.io_procs->fclose(ncdev->page_info.cfile, ncdev->page_info.cfname, true);

    ncdev->page_info.io_procs->fclose(ncdev->page_info.bfile, ncdev->page_info.bfname, true);

    ncdev->page_info.cfile = ncdev->page_info.bfile = NULL;

    /* open the main thread's files for this thread */

    strcpy(fmode, "r");                 /* read access for threads */

    strncat(fmode, gp_fmode_binary_suffix, 1);

    if ((code=cdev->page_info.io_procs->fopen(cdev->page_info.cfname, fmode, &ncdev->page_info.cfile,

                        thread_mem, thread_mem, true)) < 0 ||

         (code=cdev->page_info.io_procs->fopen(cdev->page_info.bfname, fmode, &ncdev->page_info.bfile,

                        thread_mem, thread_mem, false)) < 0)

        goto out_cleanup;

    strcpy((ncdev->page_info.cfname), (cdev->page_info.cfname));

    strcpy((ncdev->page_info.bfname), (cdev->page_info.bfname));

    clist_render_init(ncldev);      /* Initialize clist device for reading */

    ncdev->page_info.bfile_end_pos = cdev->page_info.bfile_end_pos;

    /* The threads are maintained until clist_finish_page.  At which

       point, the threads are torn down, the master clist reader device

       is changed to writer, and the icc_table and the icc_cache_cl freed */

    if (dev->icc_struct == ndev->icc_struct) {

    /* safe to share the link cache */

        ncdev->icc_cache_cl = cdev->icc_cache_cl;

        rc_increment(cdev->icc_cache_cl);   /* FIXME: needs to be incdemented safely */

    } else {

        /* each thread needs its own link cache */

        if (cachep != NULL) {

            if (*cachep == NULL) {

                /* We don't have one cached that we can reuse, so make one. */

                if ((*cachep = gsicc_cache_new(thread_mem->thread_safe_memory)) == NULL)

                    goto out_cleanup;

            }

            rc_increment(*cachep);

                ncdev->icc_cache_cl = *cachep;

        } else if ((ncdev->icc_cache_cl = gsicc_cache_new(thread_mem->thread_safe_memory)) == NULL)

            goto out_cleanup;

    }

    if (bg_print) {

        gx_device_clist_reader *ncrdev = (gx_device_clist_reader *)ncdev;

        if (cdev->icc_table != NULL) {

            /* This is a background printing thread, so it cannot share the icc_table  */

            /* since this probably was created with a GC'ed allocator and the bg_print */

            /* thread can't deal with the relocation. Free the cdev->icc_table and get */

            /* a new one from the clist.                                               */

            clist_free_icc_table(cdev->icc_table, cdev->memory);

            cdev->icc_table = NULL;

            if ((code = clist_read_icctable((gx_device_clist_reader *)ncdev)) < 0)

                goto out_cleanup;

        }

        /* Similarly for the color_usage_array, when the foreground device switches to */

        /* writer mode, the foreground's array will be freed.                          */

        if ((code = clist_read_color_usage_array(ncrdev)) < 0)

            goto out_cleanup;

    } else {

    /* Use the same profile table and color usage array in each thread */

        ncdev->icc_table = cdev->icc_table;   /* OK for multiple rendering threads */

        ((gx_device_clist_reader *)ncdev)->color_usage_array =

                ((gx_device_clist_reader *)cdev)->color_usage_array;

    }

    /* Needed for case when the target has cielab profile and pdf14 device

       has a RGB profile stored in the profile list of the clist */

    ncdev->trans_dev_icc_hash = cdev->trans_dev_icc_hash;

    /* success */

    return ndev;

out_cleanup:

    /* Close the file handles, but don't delete (unlink) the files */

    if (ncdev->page_info.bfile != NULL)

        ncdev->page_info.io_procs->fclose(ncdev->page_info.bfile, ncdev->page_info.bfname, false);

    if (ncdev->page_info.cfile != NULL)

        ncdev->page_info.io_procs->fclose(ncdev->page_info.cfile, ncdev->page_info.cfname, false);

    ncdev->do_not_open_or_close_bandfiles = true; /* we already closed the files */

    /* we can't get here with ndev == NULL */

    gdev_prn_free_memory(ndev);

    gs_free_object(thread_mem, ndev, "setup_device_and_mem_for_thread");

    gs_memory_chunk_release(thread_mem);

    return NULL;

}

/* Set up and start the render threads */

static int

clist_setup_render_threads(gx_device *dev, int y, gx_process_page_options_t *options)

{

    gx_device_printer *pdev = (gx_device_printer *)dev;

    gx_device_clist *cldev = (gx_device_clist *)dev;

    gx_device_clist_common *cdev = (gx_device_clist_common *)cldev;

    gx_device_clist_reader *crdev = &cldev->reader;

    gs_memory_t *mem = cdev->bandlist_memory;

    gs_memory_t *chunk_base_mem = mem->thread_safe_memory;

    gs_memory_status_t mem_status;

    int i, j, k, band;

    int code = 0;

    int band_count = cdev->nbands;

    int band_height = crdev->page_info.band_params.BandHeight;

    byte **reserve_memory_array = NULL;

    int reserve_pdf14_memory_size = 0;

    /* space for the halftone cache plus 2Mb for other allocations during rendering (paths, etc.) */

    /* this will be increased by the measured profile storage and icclinks (estimated).     */

    int reserve_size = 2 * 1024 * 1024 + (gx_ht_cache_default_bits_size() * dev->color_info.num_components);

    clist_icctable_entry_t *curr_entry;

    bool deep = device_is_deep(dev);

    crdev->num_render_threads = pdev->num_render_threads_requested;

    if(gs_debug[':'] != 0)

        dmprintf1(mem, "%% %d rendering threads requested.\n", pdev->num_render_threads_requested);

    if (crdev->page_uses_transparency) {

        reserve_pdf14_memory_size = (ESTIMATED_PDF14_ROW_SPACE(max(1, crdev->width), crdev->color_info.num_components, deep ? 16 : 8) >> 3);

        reserve_pdf14_memory_size *= crdev->page_info.band_params.BandHeight; /* BandHeight set by writer */

    }

    /* scan the profile table sizes to get the total each thread will need */

    if (crdev->icc_table != NULL) {

        for (curr_entry = crdev->icc_table->head; curr_entry != NULL; curr_entry = curr_entry->next) {

            reserve_size += curr_entry->serial_data.size;

            /* FIXME: Should actually measure the icclink size to device (or pdf14 blend space) */

            reserve_size += 2 * 1024 * 1024;    /* a worst case estimate */

        }

    }

    if (crdev->num_render_threads > band_count)

        crdev->num_render_threads = band_count; /* don't bother starting more threads than bands */

    /* don't exceed our limit (allow for BGPrint and main thread) */

    if (crdev->num_render_threads > MAX_THREADS - 2)

        crdev->num_render_threads = MAX_THREADS - 2;

    /* Allocate and initialize an array of thread control structures */

    crdev->render_threads = (clist_render_thread_control_t *)

              gs_alloc_byte_array(mem, crdev->num_render_threads,

                                  sizeof(clist_render_thread_control_t),

                                  "clist_setup_render_threads");

    /* fallback to non-threaded if allocation fails */

    if (crdev->render_threads == NULL) {

        emprintf(mem, " VMerror prevented threads from starting.\n");

        return_error(gs_error_VMerror);

    }

    reserve_memory_array = (byte **)gs_alloc_byte_array(mem,

                                                        crdev->num_render_threads,

                                                        sizeof(void *),

                                                        "clist_setup_render_threads");

    if (reserve_memory_array == NULL) {

        gs_free_object(mem, crdev->render_threads, "clist_setup_render_threads");

        crdev->render_threads = NULL;

        emprintf(mem, " VMerror prevented threads from starting.\n");

        return_error(gs_error_VMerror);

    }

    memset(reserve_memory_array, 0, crdev->num_render_threads * sizeof(void *));

    memset(crdev->render_threads, 0, crdev->num_render_threads *

            sizeof(clist_render_thread_control_t));

    crdev->main_thread_data = cdev->data;               /* save data area */

    /* Based on the line number requested, decide the order of band rendering */

    /* Almost all devices go in increasing line order (except the bmp* devices ) */

    crdev->thread_lookahead_direction = (y < (cdev->height - 1)) ? 1 : -1;

    band = y / band_height;

    /* If the 'mem' is not thread safe, we need to wrap it in a locking memory */

    gs_memory_status(chunk_base_mem, &mem_status);

    if (mem_status.is_thread_safe == false) {

            return_error(gs_error_VMerror);

    }

    /* If we don't have one large enough already, create an icc cache list */

    if (crdev->num_render_threads > crdev->icc_cache_list_len) {

        gsicc_link_cache_t **old = crdev->icc_cache_list;

        crdev->icc_cache_list = (gsicc_link_cache_t **)gs_alloc_byte_array(mem->thread_safe_memory,

                                    crdev->num_render_threads,

                                    sizeof(void*), "clist_render_setup_threads");

        if (crdev->icc_cache_list == NULL) {

            crdev->icc_cache_list = NULL;

            return_error(gs_error_VMerror);

        }

        if (crdev->icc_cache_list_len > 0)

            memcpy(crdev->icc_cache_list, old, crdev->icc_cache_list_len * sizeof(gsicc_link_cache_t *));

        memset(&(crdev->icc_cache_list[crdev->icc_cache_list_len]), 0,

            (crdev->num_render_threads - crdev->icc_cache_list_len) * sizeof(void *));

        crdev->icc_cache_list_len = crdev->num_render_threads;

        gs_free_object(mem, old, "clist_render_setup_threads");

    }

    /* Loop creating the devices and semaphores for each thread, then start them */

    for (i=0; (i < crdev->num_render_threads) && (band >= 0) && (band < band_count);

            i++, band += crdev->thread_lookahead_direction) {

        gx_device *ndev;

        clist_render_thread_control_t *thread = &(crdev->render_threads[i]);

        /* arbitrary extra reserve for other allocation by threads (paths, etc.) */

        /* plus the amount estimated for the pdf14 buffers */

        reserve_memory_array[i] = (byte *)gs_alloc_bytes(mem, reserve_size + reserve_pdf14_memory_size,

                                                         "clist_render_setup_threads");

        if (reserve_memory_array[i] == NULL) {

            code = gs_error_VMerror;  /* set code to an error for cleanup after the loop */

        break;

        }

        ndev = setup_device_and_mem_for_thread(chunk_base_mem, dev, false, &crdev->icc_cache_list[i]);

        if (ndev == NULL) {

            code = gs_error_VMerror;  /* set code to an error for cleanup after the loop */

            break;

        }

        thread->cdev = ndev;

        thread->memory = ndev->memory;

        thread->band = -1;              /* a value that won't match any valid band */

        thread->options = options;

        thread->buffer = NULL;

        {

            gx_device_clist *cldevl = (gx_device_clist *)ndev;

            gx_device_clist_reader *crdevl = &cldevl->reader;

            /* Both of these are only needed for the output_fn == NULL mode, but are initialized

             * regardless. */

            crdevl->curr_render_thread = i;

            crdevl->orig_clist_device = crdev;

        }

        if (options && options->init_buffer_fn) {

            code = options->init_buffer_fn(options->arg, dev, thread->memory, dev->width, band_height, &thread->buffer);

            if (code < 0)

                break;

        }

        /* create the buf device for this thread, and allocate the semaphores */

        if ((code = gdev_create_buf_device(cdev->buf_procs.create_buf_device,

                                &(thread->bdev), ndev,

                                band*crdev->page_info.band_params.BandHeight, NULL,

                                thread->memory, &(crdev->color_usage_array[0]))) < 0)

            break;

        if ((thread->sema_this = gx_semaphore_label(gx_semaphore_alloc(thread->memory), "Band")) == NULL ||

            (thread->sema_group = gx_semaphore_label(gx_semaphore_alloc(thread->memory), "Group")) == NULL) {

            code = gs_error_VMerror;

            break;

        }

        /* We don't start the threads yet until we  free up the */

        /* reserve memory we have allocated for that band. */

        thread->band = band;

    }

    /* If the code < 0, the last thread creation failed -- clean it up */

    if (code < 0) {

        /* NB: 'band' will be the one that failed, so will be the next_band needed to start */

        /* the following relies on 'free' ignoring NULL pointers */

        gx_semaphore_free(crdev->render_threads[i].sema_group);

        gx_semaphore_free(crdev->render_threads[i].sema_this);

        if (crdev->render_threads[i].bdev != NULL)

            cdev->buf_procs.destroy_buf_device(crdev->render_threads[i].bdev);

        if (crdev->render_threads[i].cdev != NULL) {

            gx_device_clist_common *thread_cdev = (gx_device_clist_common *)crdev->render_threads[i].cdev;

            /* Close the file handles, but don't delete (unlink) the files */

            thread_cdev->page_info.io_procs->fclose(thread_cdev->page_info.bfile, thread_cdev->page_info.bfname, false);

            thread_cdev->page_info.io_procs->fclose(thread_cdev->page_info.cfile, thread_cdev->page_info.cfname, false);

            thread_cdev->do_not_open_or_close_bandfiles = true; /* we already closed the files */

            gdev_prn_free_memory((gx_device *)thread_cdev);

            gs_free_object(crdev->render_threads[i].memory, thread_cdev,

            "clist_setup_render_threads");

        }

        if (crdev->render_threads[i].buffer != NULL && options && options->free_buffer_fn != NULL) {

            options->free_buffer_fn(options->arg, dev, crdev->render_threads[i].memory, crdev->render_threads[i].buffer);

            crdev->render_threads[i].buffer = NULL;

        }

        if (crdev->render_threads[i].memory != NULL) {

            gs_memory_chunk_release(crdev->render_threads[i].memory);

            crdev->render_threads[i].memory = NULL;

        }

    }

    /* If we weren't able to create at least one thread, punt   */

    /* Although a single thread isn't any more efficient, the   */

    /* machinery still works, so that's OK.                     */

    if (i == 0) {

        if (crdev->render_threads[0].memory != NULL) {

            gs_memory_chunk_release(crdev->render_threads[0].memory);

            if (chunk_base_mem != mem) {

                gs_free_object(mem, chunk_base_mem, "clist_setup_render_threads(locked allocator)");

            }

        }

        gs_free_object(mem, crdev->render_threads, "clist_setup_render_threads");

        crdev->render_threads = NULL;

        /* restore the file pointers */

        if (cdev->page_info.cfile == NULL) {

            char fmode[4];

            strcpy(fmode, "a+");        /* file already exists and we want to re-use it */

            strncat(fmode, gp_fmode_binary_suffix, 1);

            cdev->page_info.io_procs->fopen(cdev->page_info.cfname, fmode, &cdev->page_info.cfile,

                                mem, cdev->bandlist_memory, true);

            cdev->page_info.io_procs->fseek(cdev->page_info.cfile, 0, SEEK_SET, cdev->page_info.cfname);

            cdev->page_info.io_procs->fopen(cdev->page_info.bfname, fmode, &cdev->page_info.bfile,

                                mem, cdev->bandlist_memory, false);

            cdev->page_info.io_procs->fseek(cdev->page_info.bfile, 0, SEEK_SET, cdev->page_info.bfname);

        }

        emprintf1(mem, "Rendering threads not started, code=%d.\n", code);

        return_error(code);

    }

    k = crdev->num_render_threads;

    crdev->num_render_threads = i;

    crdev->curr_render_thread = 0;

    crdev->next_band = band;

    /* Free up any "reserve" memory we may have allocated, and start the

     * threads since we deferred that in the thread setup loop above.

     * We know if we get here we can start at least 1 thread.

     */

    for (j=0, code = 0; j<k; j++) {

        gs_free_object(mem, reserve_memory_array[j], "clist_setup_render_threads");

        if (code == 0 && j < i)

            code = clist_start_render_thread(dev, j, crdev->render_threads[j].band);

    }

    gs_free_object(mem, reserve_memory_array, "clist_setup_render_threads");

    if(gs_debug[':'] != 0)

        dmprintf1(mem, "%% Using %d rendering threads\n", i);

    return code;

}

/* This is also exported for teardown after background printing */

void

teardown_device_and_mem_for_thread(gx_device *dev, gp_thread_id thread_id, bool bg_print)

{

    gx_device_clist_common *thread_cdev = (gx_device_clist_common *)dev;

    gx_device_clist_reader *thread_crdev = (gx_device_clist_reader *)dev;

    gs_memory_t *thread_memory = dev->memory;

    /* First finish the thread */

    gp_thread_finish(thread_id);

    if (bg_print) {

        /* we are cleaning up a background printing thread, so we clean up similarly to */

        /* what is done  by clist_finish_page, but without re-opening the clist files.  */

        clist_teardown_render_threads(dev); /* we may have used multiple threads */

        /* free the thread's icc_table since this was not done by clist_finish_page */

        clist_free_icc_table(thread_crdev->icc_table, thread_memory);

        thread_crdev->icc_table = NULL;

        /* NB: gdev_prn_free_memory below will free the color_usage_array */

    } else {

        /* make sure this doesn't get freed by gdev_prn_free_memory below */

        ((gx_device_clist_reader *)thread_cdev)->color_usage_array = NULL;

        /* For non-bg_print cases the icc_table is shared between devices, but

         * is not reference counted or anything. We rely on it being shared with

         * and owned by the "parent" device in the interpreter thread, hence

         * null it here to avoid it being freed as we cleanup the thread device.

         */

        thread_crdev->icc_table = NULL;

    }

    rc_decrement(thread_crdev->icc_cache_cl, "teardown_render_thread");

    thread_crdev->icc_cache_cl = NULL;

    /*

     * Free the BufferSpace, close the band files, optionally unlinking them.

     * We unlink the files if this call is cleaning up from bg printing.

     * Note that the BufferSpace is freed using 'ppdev->buf' so the 'data'

     * pointer doesn't need to be the one that the thread started with

     */

    /* If this thread was being used for background printing and NumRenderingThreads > 0 */

    /* the clist_setup_render_threads may have already closed these files                */

    /* Note that in the case of back ground printing, we only want to close the instance  */

    /* of the files for the reader (hence the final parameter being false). We'll clean  */

    /* the original instance of the files in prn_finish_bg_print()                       */

    if (thread_cdev->page_info.bfile != NULL)

        thread_cdev->page_info.io_procs->fclose(thread_cdev->page_info.bfile, thread_cdev->page_info.bfname, false);

    if (thread_cdev->page_info.cfile != NULL)

        thread_cdev->page_info.io_procs->fclose(thread_cdev->page_info.cfile, thread_cdev->page_info.cfname, false);

    thread_cdev->page_info.bfile = thread_cdev->page_info.cfile = NULL;

    thread_cdev->do_not_open_or_close_bandfiles = true; /* we already closed the files */

    gdev_prn_free_memory((gx_device *)thread_cdev);

    /* Free the device copy this thread used.  Note that the

       deviceN stuff if was allocated and copied earlier for the device

       will be freed with this call and the icc_struct ref count will be decremented. */

    gs_free_object(thread_memory, thread_cdev, "clist_teardown_render_threads");

#ifdef DEBUG

    dmprintf(thread_memory, "rendering thread ending memory state...\n");

    gs_memory_chunk_dump_memory(thread_memory);

    dmprintf(thread_memory, "                                    memory dump done.\n");

#endif

    gs_memory_chunk_release(thread_memory);

}

void

clist_teardown_render_threads(gx_device *dev)

{

    gx_device_clist *cldev = (gx_device_clist *)dev;

    gx_device_clist_common *cdev = (gx_device_clist_common *)dev;

    gx_device_clist_reader *crdev = &cldev->reader;

    gs_memory_t *mem = cdev->bandlist_memory;

    int i;

    if (crdev->render_threads != NULL) {

        /* Wait for all threads to finish */

        for (i = (crdev->num_render_threads - 1); i >= 0; i--) {

            clist_render_thread_control_t *thread = &(crdev->render_threads[i]);

            if (thread->status == THREAD_BUSY)

                gx_semaphore_wait(thread->sema_this);

        }

        /* then free each thread's memory */

        for (i = (crdev->num_render_threads - 1); i >= 0; i--) {

            clist_render_thread_control_t *thread = &(crdev->render_threads[i]);

            gx_device_clist_common *thread_cdev = (gx_device_clist_common *)thread->cdev;

            /* Free control semaphores */

            gx_semaphore_free(thread->sema_group);

            gx_semaphore_free(thread->sema_this);

            /* destroy the thread's buffer device */

            thread_cdev->buf_procs.destroy_buf_device(thread->bdev);

            if (thread->options) {

                if (thread->options->free_buffer_fn && thread->buffer) {

                    thread->options->free_buffer_fn(thread->options->arg, dev, thread->memory, thread->buffer);

                    thread->buffer = NULL;

                }

                thread->options = NULL;

            }

            /* before freeing this device's memory, swap with cdev if it was the main_thread_data */

            if (thread_cdev->data == crdev->main_thread_data) {

                thread_cdev->data = cdev->data;

                cdev->data = crdev->main_thread_data;

            }

#ifdef DEBUG

            if (gs_debug[':'])

                dmprintf2(thread->memory, "%% Thread %d total usertime=%ld msec\n", i, thread->cputime);

            dmprintf1(thread->memory, "\nThread %d ", i);

#endif

            teardown_device_and_mem_for_thread((gx_device *)thread_cdev, thread->thread, false);

        }

        gs_free_object(mem, crdev->render_threads, "clist_teardown_render_threads");

        crdev->render_threads = NULL;

        /* Now re-open the clist temp files so we can write to them */

        if (cdev->page_info.cfile == NULL) {

            char fmode[4];

            strcpy(fmode, "a+");        /* file already exists and we want to re-use it */

            strncat(fmode, gp_fmode_binary_suffix, 1);

            cdev->page_info.io_procs->fopen(cdev->page_info.cfname, fmode, &cdev->page_info.cfile,

                                mem, cdev->bandlist_memory, true);

            cdev->page_info.io_procs->fseek(cdev->page_info.cfile, 0, SEEK_SET, cdev->page_info.cfname);

            cdev->page_info.io_procs->fopen(cdev->page_info.bfname, fmode, &cdev->page_info.bfile,

                                mem, cdev->bandlist_memory, false);

            cdev->page_info.io_procs->fseek(cdev->page_info.bfile, 0, SEEK_SET, cdev->page_info.bfname);

        }

    }

}

static int

clist_start_render_thread(gx_device *dev, int thread_index, int band)

{

    gx_device_clist *cldev = (gx_device_clist *)dev;

    gx_device_clist_reader *crdev = &cldev->reader;

    int code;

    gp_thread_creation_callback_t starter;

    gx_process_page_options_t* options = crdev->render_threads[thread_index].options;

    crdev->render_threads[thread_index].band = band;

    /* Finally, fire it up */

    if (options == NULL || options->output_fn) {

        /* Traditional mechanism, using output_fn. Each thread will

         * block after it renders until it has been output 'in-order'

         * using output_fn. */

        crdev->render_threads[thread_index].status = THREAD_BUSY;

        starter = clist_render_thread;

    } else {

        /* New mechanism, with output_fn == NULL. process_fn is

         * required to both render and output the data. Less blocking

         * required, and potentially significant speedups as long as

         * output does not need to be 'in-order'. */

        starter = clist_render_thread_no_output_fn;

        /* This could pretty much be an assert. */

        if (options == NULL || options->process_fn == NULL)

            return_error(gs_error_rangecheck);

    }

    code = gp_thread_start(starter,

                           &(crdev->render_threads[thread_index]),

                           &(crdev->render_threads[thread_index].thread));

    gp_thread_label(crdev->render_threads[thread_index].thread, "Band");

    return code;

}

static void

clist_render_thread(void *data)

{

    clist_render_thread_control_t *thread = (clist_render_thread_control_t *)data;

    gx_device *dev = thread->cdev;

    gx_device_clist *cldev = (gx_device_clist *)dev;

    gx_device_clist_reader *crdev = &cldev->reader;

    gx_device *bdev = thread->bdev;

    gs_int_rect band_rect;

    byte *mdata = crdev->data + crdev->page_info.tile_cache_size;

    byte *mlines = (crdev->page_info.line_ptrs_offset == 0 ? NULL : mdata + crdev->page_info.line_ptrs_offset);

    uint raster = gx_device_raster_plane(dev, NULL);

    int code;

    int band_height = crdev->page_info.band_params.BandHeight;

    int band = thread->band;

    int band_begin_line = band * band_height;

    int band_end_line = band_begin_line + band_height;

    int band_num_lines;

#ifdef DEBUG

    long starttime[2], endtime[2];

    gp_get_usertime(starttime); /* thread start time */

#endif

    if (band_end_line > dev->height)

        band_end_line = dev->height;

    band_num_lines = band_end_line - band_begin_line;

    code = crdev->buf_procs.setup_buf_device

            (bdev, mdata, raster, (byte **)mlines, 0, band_num_lines, band_num_lines);

    band_rect.p.x = 0;

    band_rect.p.y = band_begin_line;

    band_rect.q.x = dev->width;

    band_rect.q.y = band_end_line;

    if (code >= 0)

        code = clist_render_rectangle(cldev, &band_rect, bdev, NULL, true);

    if (code >= 0 && thread->options && thread->options->process_fn)

        code = thread->options->process_fn(thread->options->arg, dev, bdev, &band_rect, thread->buffer);

    /* Reset the band boundaries now */

    crdev->ymin = band_begin_line;

    crdev->ymax = band_end_line;

    crdev->offset_map = NULL;

    if (code < 0)

        thread->status = THREAD_ERROR;          /* shouldn't happen */

    else

        thread->status = THREAD_DONE;    /* OK */

#ifdef DEBUG

    gp_get_usertime(endtime);

    thread->cputime += (endtime[0] - starttime[0]) * 1000 +

             (endtime[1] - starttime[1]) / 1000000;

#endif

    /*

     * Signal the semaphores. We signal the 'group' first since even if

     * the waiter is released on the group, it still needs to check

     * status on the thread

     */

    gx_semaphore_signal(thread->sema_group);

    gx_semaphore_signal(thread->sema_this);

}

/* Used if output_fn == NULL. No blocking required as we no longer need to

 * serialise the calls to output_fn. */

static void

clist_render_thread_no_output_fn(void* data)

{

    clist_render_thread_control_t* thread = (clist_render_thread_control_t*)data;

    gx_device* dev = thread->cdev;

    gx_device_clist* cldev = (gx_device_clist*)dev;

    gx_device_clist_reader* crdev = &cldev->reader;

    gx_device* bdev = thread->bdev;

    gs_int_rect band_rect;

    byte* mdata = crdev->data + crdev->page_info.tile_cache_size;

    byte* mlines = (crdev->page_info.line_ptrs_offset == 0 ? NULL : mdata + crdev->page_info.line_ptrs_offset);

    uint raster = gx_device_raster_plane(dev, NULL);

    int code;

    int band_height = crdev->page_info.band_params.BandHeight;

    int band_begin_line = thread->band * band_height;

    int band_end_line = band_begin_line + band_height;

    int band_num_lines;

#ifdef DEBUG

    long starttime[2], endtime[2];

    gp_get_usertime(starttime); /* thread start time */

#endif

    /*

      As long there is no need for calling the bands 'in order' we can

      process multiple bands with one thread while there are free

      (unprocessed) bands available. The only potential race condition

      here is where we need to pick a new band to draw when a thread

      finishes its render task. We delegate the job of doing this to the

      process_fn itself, enabling devices to make use of less expensive

      operations (such as fast interlocked exchange with add) that may

      not be available portably.

      If there is no more unprocessed band the thread will finish, giving

      back the control to the main process (obviously after ALL the

      rendering threads have got finished).

    */

    while (band_begin_line < dev->height && band_end_line > 0) {

        if (band_end_line > dev->height)

            band_end_line = dev->height;

        band_num_lines = band_end_line - band_begin_line;

        ((gx_device_memory*)bdev)->band_y = band_begin_line; /* probably useless, but doesn't hurt */

        code = crdev->buf_procs.setup_buf_device

        (bdev, mdata, raster, (byte**)mlines, 0, band_num_lines, band_num_lines);

        band_rect.p.x = 0;

        band_rect.p.y = band_begin_line;

        band_rect.q.x = dev->width;

        band_rect.q.y = band_end_line;

        if (code >= 0)

            code = clist_render_rectangle(cldev, &band_rect, bdev, NULL, true);

        if (code >= 0)

            code = thread->options->process_fn(thread->options->arg, dev, bdev, &band_rect, thread->buffer);

        /* A side effect of the process_fn is that it should select the next

          * band for this thread to render. It does this by updating

          * crdev->next_band (that's the thread's own device!), as well as

          * updating crdev_orig so that other threads won't try to render the

          * same thread (normally by updating crdev_orig->next_band). */

        band_begin_line = crdev->next_band * band_height;