Panda3D

Public Member Functions | Public Attributes | List of all members
PipelineCyclerTrivialImpl Struct Reference

This is the trivial, non-threaded implementation of PipelineCyclerBase. More...

`#include "pipelineCyclerTrivialImpl.h"`

Inheritance diagram for PipelineCyclerTrivialImpl:

## Public Member Functions
| PipelineCyclerTrivialImpl (const PipelineCyclerTrivialImpl &copy)=delete
| PipelineCyclerTrivialImpl (CycleData *initial_data, Pipeline *pipeline=nullptr)
void | acquire (Thread *current_thread=nullptr)
| Grabs an overall lock on the cycler. More...
CycleData * | cheat () const
| Returns a pointer without counting it. More...
CycleData * | elevate_read (const CycleData *pointer, Thread *current_thread)
| Elevates a currently-held read pointer into a write pointer. More...
CycleData * | elevate_read_stage (int pipeline_stage, const CycleData *pointer, Thread *current_thread)
| Elevates a currently-held read pointer into a write pointer. More...
CycleData * | elevate_read_stage_upstream (int pipeline_stage, const CycleData *pointer, bool force_to_0, Thread *current_thread)
| Elevates a currently-held read pointer into a write pointer. More...
CycleData * | elevate_read_upstream (const CycleData *pointer, bool force_to_0, Thread *current_thread)
| Elevates a currently-held read pointer into a write pointer, like elevate_read(), but also propagates the pointer back to upstream stages, like write_upstream(). More...
int | get_num_stages ()
| Returns the number of stages in the pipeline. More...
TypeHandle | get_parent_type () const
| Returns the type of object that owns this cycler, as reported by CycleData::get_parent_type(). More...
int | get_read_count () const
| Returns the number of handles currently outstanding to read the current stage of the data. More...
int | get_write_count () const
| Returns the number of handles currently outstanding to read the current stage of the data. More...
void | increment_read (const CycleData *pointer) const
| Increments the count on a pointer previously retrieved by read(); now the pointer will need to be released twice. More...
void | increment_write (CycleData *pointer) const
| Increments the count on a pointer previously retrieved by write(); now the pointer will need to be released twice. More...
PipelineCyclerTrivialImpl & | operator= (const PipelineCyclerTrivialImpl &copy)=delete
const CycleData * | read (Thread *current_thread) const
| Returns a const CycleData pointer, filled with the data for the current stage of the pipeline as seen by this thread. More...
const CycleData * | read_stage (int pipeline_stage, Thread *current_thread) const
| Returns a const CycleData pointer, filled with the data for the indicated pipeline stage. More...
const CycleData * | read_stage_unlocked (int pipeline_stage) const
| Returns a const CycleData pointer, filled with the data for the indicated stage of the pipeline. More...
const CycleData * | read_unlocked (Thread *current_thread) const
| Returns a const CycleData pointer, filled with the data for the current stage of the pipeline as seen by this thread. More...
void | release ()
| Release the overall lock on the cycler that was grabbed via acquire(). More...
void | release_read (const CycleData *pointer) const
| Releases a pointer previously obtained via a call to read(). More...
void | release_read_stage (int pipeline_stage, const CycleData *pointer) const
| Releases a pointer previously obtained via a call to read_stage(). More...
void | release_write (CycleData *pointer)
| Releases a pointer previously obtained via a call to write(). More...
void | release_write_stage (int pipeline_stage, CycleData *pointer)
| Releases a pointer previously obtained via a call to write_stage(). More...
CycleData * | write (Thread *current_thread)
| Returns a non-const CycleData pointer, filled with a unique copy of the data for the current stage of the pipeline as seen by this thread. More...
CycleData * | write_stage (int pipeline_stage, Thread *current_thread)
| Returns a pointer suitable for writing to the nth stage of the pipeline. More...
CycleData * | write_stage_upstream (int pipeline_stage, bool force_to_0, Thread *current_thread)
| Returns a pointer suitable for writing to the nth stage of the pipeline. More...
CycleData * | write_upstream (bool force_to_0, Thread *current_thread)
| This special variant on write() will automatically propagate changes back to upstream pipeline stages. More...

## Public Attributes
CycleData * | _data

## Detailed Description

This is the trivial, non-threaded implementation of PipelineCyclerBase.

It is only compiled when DO_PIPELINING is not defined (which usually implies that threading is not available).

This implementation is designed to do as little as possible, and to compile to nothing, or almost nothing. It doesn't actually support pipelining in any way. It doesn't even perform any sanity checks to speak of. It's designed for a strictly single-threaded application, and its purpose is to be as low-overhead as possible.

We define this as a struct instead of a class to emphasize the importance of byte placement within the object, so that the inherited struct's data is likely to be placed by the compiler at the "this" pointer.

Definition at line 41 of file pipelineCyclerTrivialImpl.h.

## Member Function Documentation

## ◆ acquire()

void PipelineCyclerTrivialImpl::acquire | ( | Thread * | current_thread = `nullptr` | ) |
| inline

Grabs an overall lock on the cycler.

Release it with a call to release(). This lock should be held while walking the list of stages.

Definition at line 37 of file pipelineCyclerTrivialImpl.I.

## ◆ cheat()

CycleData * PipelineCyclerTrivialImpl::cheat | ( |  | ) | const
| inline

Returns a pointer without counting it.

This is only intended for use as the return value for certain nassertr() functions, so the application can recover after a failure to manage the read and write pointers correctly. You should never call this function directly.

Definition at line 310 of file pipelineCyclerTrivialImpl.I.

## ◆ elevate_read()

CycleData * PipelineCyclerTrivialImpl::elevate_read | ( | const CycleData * | pointer,
|  | Thread * | current_thread
| ) |  |
| inline

Elevates a currently-held read pointer into a write pointer.

This may or may not change the value of the pointer. It is only valid to do this if this is the only currently-outstanding read pointer on the current stage.

Definition at line 149 of file pipelineCyclerTrivialImpl.I.

## ◆ elevate_read_stage()

CycleData * PipelineCyclerTrivialImpl::elevate_read_stage | ( | int | pipeline_stage,
|  | const CycleData * | pointer,
|  | Thread * | current_thread
| ) |  |
| inline

Elevates a currently-held read pointer into a write pointer.

This may or may not change the value of the pointer. It is only valid to do this if this is the only currently-outstanding read pointer on the current stage.

Definition at line 265 of file pipelineCyclerTrivialImpl.I.

## ◆ elevate_read_stage_upstream()

CycleData * PipelineCyclerTrivialImpl::elevate_read_stage_upstream | ( | int | pipeline_stage,
|  | const CycleData * | pointer,
|  | bool | force_to_0,
|  | Thread * | current_thread
| ) |  |
| inline

Elevates a currently-held read pointer into a write pointer.

This may or may not change the value of the pointer. It is only valid to do this if this is the only currently-outstanding read pointer on the current stage.

Definition at line 279 of file pipelineCyclerTrivialImpl.I.

## ◆ elevate_read_upstream()

CycleData * PipelineCyclerTrivialImpl::elevate_read_upstream | ( | const CycleData * | pointer,
|  | bool | force_to_0,
|  | Thread * | current_thread
| ) |  |
| inline

Elevates a currently-held read pointer into a write pointer, like elevate_read(), but also propagates the pointer back to upstream stages, like write_upstream().

Definition at line 163 of file pipelineCyclerTrivialImpl.I.

## ◆ get_num_stages()

int PipelineCyclerTrivialImpl::get_num_stages | ( |  | ) |
| inline

Returns the number of stages in the pipeline.

Definition at line 190 of file pipelineCyclerTrivialImpl.I.

## ◆ get_parent_type()

TypeHandle PipelineCyclerTrivialImpl::get_parent_type | ( |  | ) | const
| inline

Returns the type of object that owns this cycler, as reported by CycleData::get_parent_type().

Definition at line 299 of file pipelineCyclerTrivialImpl.I.

## ◆ get_read_count()

int PipelineCyclerTrivialImpl::get_read_count | ( |  | ) | const
| inline

Returns the number of handles currently outstanding to read the current stage of the data.

This should only be used for debugging purposes.

Definition at line 323 of file pipelineCyclerTrivialImpl.I.

## ◆ get_write_count()

int PipelineCyclerTrivialImpl::get_write_count | ( |  | ) | const
| inline

Returns the number of handles currently outstanding to read the current stage of the data.

This will normally only be either 0 or 1. This should only be used for debugging purposes.

Definition at line 333 of file pipelineCyclerTrivialImpl.I.

## ◆ increment_read()

void PipelineCyclerTrivialImpl::increment_read | ( | const CycleData * | pointer | ) | const
| inline

Increments the count on a pointer previously retrieved by read(); now the pointer will need to be released twice.

Definition at line 84 of file pipelineCyclerTrivialImpl.I.

## ◆ increment_write()

void PipelineCyclerTrivialImpl::increment_write | ( | CycleData * | pointer | ) | const
| inline

Increments the count on a pointer previously retrieved by write(); now the pointer will need to be released twice.

Definition at line 176 of file pipelineCyclerTrivialImpl.I.

## ◆ read()

const CycleData * PipelineCyclerTrivialImpl::read | ( | Thread * | current_thread | ) | const
| inline

Returns a const CycleData pointer, filled with the data for the current stage of the pipeline as seen by this thread.

This pointer should eventually be released by calling release_read().

Definition at line 71 of file pipelineCyclerTrivialImpl.I.

Referenced by BamWriter::write_cdata().

## ◆ read_stage()

const CycleData * PipelineCyclerTrivialImpl::read_stage | ( | int | pipeline_stage,
|  | Thread * | current_thread
| ) |  | const
| inline

Returns a const CycleData pointer, filled with the data for the indicated pipeline stage.

This pointer should eventually be released by calling release_read().

Definition at line 214 of file pipelineCyclerTrivialImpl.I.

## ◆ read_stage_unlocked()

const CycleData * PipelineCyclerTrivialImpl::read_stage_unlocked | ( | int | pipeline_stage | ) | const
| inline

Returns a const CycleData pointer, filled with the data for the indicated stage of the pipeline.

As in read_unlocked(), no lock is held on the returned pointer.

Definition at line 200 of file pipelineCyclerTrivialImpl.I.

## ◆ read_unlocked()

const CycleData * PipelineCyclerTrivialImpl::read_unlocked | ( | Thread * | current_thread | ) | const
| inline

Returns a const CycleData pointer, filled with the data for the current stage of the pipeline as seen by this thread.

No lock is made on the contents; there is no guarantee that some other thread won't modify this object's data while you are working on it. (However, the data within the returned CycleData object itself is safe from modification; if another thread modifies the data, it will perform a copy-on-write, and thereby change the pointer stored within the object.)

Definition at line 57 of file pipelineCyclerTrivialImpl.I.

## ◆ release()

void PipelineCyclerTrivialImpl::release | ( |  | ) |
| inline

Release the overall lock on the cycler that was grabbed via acquire().

Definition at line 44 of file pipelineCyclerTrivialImpl.I.

## ◆ release_read()

void PipelineCyclerTrivialImpl::release_read | ( | const CycleData * | pointer | ) | const
| inline

Releases a pointer previously obtained via a call to read().

Definition at line 91 of file pipelineCyclerTrivialImpl.I.

Referenced by BamWriter::write_cdata().

## ◆ release_read_stage()

void PipelineCyclerTrivialImpl::release_read_stage | ( | int | pipeline_stage,
|  | const CycleData * | pointer
| ) |  | const
| inline

Releases a pointer previously obtained via a call to read_stage().

Definition at line 226 of file pipelineCyclerTrivialImpl.I.

## ◆ release_write()

void PipelineCyclerTrivialImpl::release_write | ( | CycleData * | pointer | ) |
| inline

Releases a pointer previously obtained via a call to write().

Definition at line 183 of file pipelineCyclerTrivialImpl.I.

Referenced by BamReader::read_cdata().

## ◆ release_write_stage()

void PipelineCyclerTrivialImpl::release_write_stage | ( | int | pipeline_stage,
|  | CycleData * | pointer
| ) |  |
| inline

Releases a pointer previously obtained via a call to write_stage().

Definition at line 291 of file pipelineCyclerTrivialImpl.I.

## ◆ write()

CycleData * PipelineCyclerTrivialImpl::write | ( | Thread * | current_thread | ) |
| inline

Returns a non-const CycleData pointer, filled with a unique copy of the data for the current stage of the pipeline as seen by this thread.

This pointer may now be used to write to the data, and that copy of the data will be propagated to all later stages of the pipeline. This pointer should eventually be released by calling release_write().

There may only be one outstanding write pointer on a given stage at a time, and if there is a write pointer there may be no read pointers on the same stage (but see elevate_read).

Definition at line 106 of file pipelineCyclerTrivialImpl.I.

Referenced by BamReader::read_cdata().

## ◆ write_stage()

CycleData * PipelineCyclerTrivialImpl::write_stage | ( | int | pipeline_stage,
|  | Thread * | current_thread
| ) |  |
| inline

Returns a pointer suitable for writing to the nth stage of the pipeline.

This is for special applications that need to update the entire pipeline at once (for instance, to remove an invalid pointer). This pointer should later be released with release_write_stage().

Definition at line 236 of file pipelineCyclerTrivialImpl.I.

## ◆ write_stage_upstream()

CycleData * PipelineCyclerTrivialImpl::write_stage_upstream | ( | int | pipeline_stage,
|  | bool | force_to_0,
|  | Thread * | current_thread
| ) |  |
| inline

Returns a pointer suitable for writing to the nth stage of the pipeline.

This is for special applications that need to update the entire pipeline at once (for instance, to remove an invalid pointer). This pointer should later be released with release_write_stage().

Definition at line 251 of file pipelineCyclerTrivialImpl.I.

## ◆ write_upstream()

CycleData * PipelineCyclerTrivialImpl::write_upstream | ( | bool | force_to_0,
|  | Thread * | current_thread
| ) |  |
| inline

This special variant on write() will automatically propagate changes back to upstream pipeline stages.

If force_to_0 is false, then it propagates back only as long as the CycleData pointers are equivalent, guaranteeing that it does not modify upstream data (other than the modification that will be performed by the code that returns this pointer). This is particularly appropriate for minor updates, where it doesn't matter much if the update is lost, such as storing a cached value.

If force_to_0 is trivial, then the CycleData pointer for the current pipeline stage is propagated all the way back up to stage 0; after this call, there will be only one CycleData pointer that is duplicated in all stages between stage 0 and the current stage. This may undo some recent changes that were made independently at pipeline stage 0 (or any other upstream stage). However, it guarantees that the change that is to be applied at this pipeline stage will stick. This is slightly dangerous because of the risk of losing upstream changes; generally, this should only be done when you are confident that there are no upstream changes to be lost (for instance, for an object that has been recently created).

Definition at line 135 of file pipelineCyclerTrivialImpl.I.

The documentation for this struct was generated from the following files:

- panda/src/pipeline/pipelineCyclerTrivialImpl.h
- panda/src/pipeline/pipelineCyclerTrivialImpl.I