Class OutputPortBase
Non-generic base class for dataflow data output and error output ports, containing the functionality that doesn't depend on the type of the row class.
The library user does not derive new port classes directly from
OutputPortBase, but instead creates or uses instances of the derived class
OutputPort<TOutput> and ErrorOutputPort<TError>.
Note: As per normal, unless otherwise noted, the instance members are not thread-safe, and should only be accessed from the worker that the port belongs to.
Namespace: actionETL
Assembly: actionETL.dll
Syntax
public abstract class OutputPortBaseProperties
ActiveDuration
Gets the nullable duration since the port became active, either until the current time, or until the port completed, whichever is earlier.
Note: This property is thread-safe.
Declaration
public Duration? ActiveDuration { get; }Property Value
| Type | Description |
|---|---|
| Nullable<Duration> | The nullable duration. |
BufferCapacity
Gets the port buffer capacity, which is the recommended and maximum
number of rows to send synchronously in one batch. It is also
the row demand available when HasBufferDemandAsync()
or HasBufferDemand return true.
Increasing BufferCapacity can improve performance, but also consumes
more memory. Setting BufferCapacity too large should be avoided,
since it can cause the application to swap large amounts of memory out to disk,
leading to drastically reduced performance.
Defaults to 256 rows. To change it, set the downstream InputPort.BufferCapacity before the worker or its siblings starts, or set the InputPortRowsPerBuffer configuration value before the port is created.
Also see PortBufferingMode, and Dataflow Blocking and Row Buffering.
Note: Reading this property is thread-safe.
Declaration
[Obsolete("Use RowsPerBuffer instead.")]
public int BufferCapacity { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The buffer capacity as number of rows. |
DebugBreakAfterRows
Gets or sets the number of rows sent after which to break any attached debugger.
A value of zero will break every time rows are sent, while e.g. a value of
10000 will only start breaking after that many rows have been sent.
Any negative value will disable breaking on rows.
Also see DebugCommands and
SetDebugCommands(DebugPortCommands, Int64).
Note: This property is thread-safe.
Declaration
public long DebugBreakAfterRows { get; set; }Property Value
| Type | Description |
|---|---|
| Int64 | When setting the value: If zero or greater, and OnRows is not set, then BreakOnRowsAndStateCompleted will also be added to DebugCommands. This allows enabling breaking after a particular number of rows and state completed with a single setting. If less than zero, and DebugCommands is exactly BreakOnRowsAndStateCompleted, then DebugCommands will be set to None. If less than zero, but DebugCommands is not exactly BreakOnRowsAndStateCompleted, then only OnRows will be unset from DebugCommands |
DebugCommands
Gets or sets commands for when to launch or break a debugger when debugging dataflow ports.
Multiple commands can be set at the same time by combining them with bitwise OR
(| in C#).
The various "On..." commands defines when to break or launch the debugger, while Launch and Break defines what to do, i.e. launching or breaking the debugger. In most debugging scenarios, both one or more "On..." commands, as well as Launch or Break, should be set.
There are also several predefined combinations, e.g. BreakOnRowsAndStateCompleted that is very useful for viewing rows sent from an output or error output port.
Note: Setting OnRows will also set
DebugBreakAfterRows to zero, if the latter is not already zero or greater.
Unsetting OnRows will also set
DebugBreakAfterRows to -1, if the latter is not already less than zero.
Note: Any Launch command will be automatically downgraded to a Break command after the first attempt to launch a debugger.
Note: that to view the dataflow rows while debugging, DebugCommands must be set to something other than None when the port worker initially runs.
Note: This property is thread-safe.
Declaration
public DebugPortCommands DebugCommands { get; set; }Property Value
| Type | Description |
|---|---|
| DebugPortCommands |
See Also
InstantActive
Gets the nullable instant the port changed state to Active.
Note: This property is thread-safe.
Declaration
public Instant? InstantActive { get; }Property Value
| Type | Description |
|---|---|
| Nullable<Instant> | The nullable instant. |
InstantCompleted
Gets the nullable instant the port completed.
Note: This property is thread-safe.
Declaration
public Instant? InstantCompleted { get; }Property Value
| Type | Description |
|---|---|
| Nullable<Instant> | The nullable instant. |
IsErrorOutput
Returns true if this port is an ErrorOutputPort<TError>;
false if it is an OutputPort<TOutput>.
Note: This property is thread-safe.
Declaration
public bool IsErrorOutput { get; }Property Value
| Type | Description |
|---|---|
| Boolean |
IsLinked
Returns true if this port is linked to a downstream input port;
otherwise, false.
Note: This property is thread-safe.
Declaration
public bool IsLinked { get; }Property Value
| Type | Description |
|---|---|
| Boolean |
LinkedTo
Gets the downstream input port this output (or error output) port is linked to,
or null if it is not linked.
Note: This property is thread-safe.
Declaration
public InputPort LinkedTo { get; }Property Value
| Type | Description |
|---|---|
| InputPort |
Locator
Gets the locator string, which represents where in the worker hierarchy this port resides.
It consists of the names of the worker system and all ancestor workers, separated by
/, followed by the port type and its name, e.g.:
/Root/Extract Products/Read CSV Product File.Outputs[LeftOutput]
or /Root/Extract Products/Read CSV Product File.ErrorOutputs[LeftErrorOutput].
This property is thread-safe.
Declaration
public string Locator { get; }Property Value
| Type | Description |
|---|---|
| String | The port locator string. |
Logger
Gets the logger instance for this port, which should be used for logging messages
related to this port. The logger's name is set to the Locator string of the port,
which will appear in the logged output.
This property is thread-safe.
This property is thread-safe.
Declaration
public ALog Logger { get; }Property Value
| Type | Description |
|---|---|
| ALog |
Name
Gets the port name.
This property is thread-safe.
Declaration
public string Name { get; }Property Value
| Type | Description |
|---|---|
| String |
RowsPerBuffer
Gets the port buffer capacity, which is the recommended and maximum
number of rows when sending or taking rows to or from the ports
synchronously in batches.
Note that you can only get the value on the output port, but you
can both get and set this value on the input port.
See Port RowsPerBuffer and WorkerParent.BytesPerRowBuffer
for full details.
By default and when InputPort.RowsPerBuffer is not set, RowsPerBuffer
is automatically calculated by dividing BytesPerRowBuffer
with an upfront estimate of the average row size in bytes. The calculation is then
skewed to reduce the likelihood of using very small buffers (64 rows or less).
In most cases, this approach results in a good balance
between dataflow memory use, buffering to avoid row starvation, and speed of
dataflow transfers.
Increasing RowsPerBuffer (on the downstream input port)
can improve performance, but also consumes
more memory. Setting RowsPerBuffer too large should be avoided,
since it can cause the application to swap large amounts of memory out to disk,
leading to drastically reduced performance.
You can set the value with the AConfig configuration,
using the InputPortRowsPerBuffer key,
before the port is created, either as a global setting, or for a specific
input port.
Alternatively, set this property before the worker or its siblings run,
which will also override any AConfig setting.
The value is automatically rounded up to the nearest power of two.
Any value less than 1 will be set to the default value.
Note: This property is thread-safe.
Declaration
public int RowsPerBuffer { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The buffer capacity as number of rows. |
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Cannot get output port RowsPerBuffer until the port is linked. |
RowsSent
Gets the number of rows sent to this output port.
Note: this property is only thread-safe for other workers etc. to read after the port has completed.
Declaration
public long RowsSent { get; }Property Value
| Type | Description |
|---|---|
| Int64 |
State
Gets the port state.
This property is thread-safe.
Declaration
public OutputPortBaseState State { get; }Property Value
| Type | Description |
|---|---|
| OutputPortBaseState |
Worker
Gets the worker instance this port belongs to.
This property is thread-safe.
Declaration
public WorkerBase Worker { get; }Property Value
| Type | Description |
|---|---|
| WorkerBase |
Methods
SendError(String)
Activates (if needed) and completes the port with an Error state, or throws
an exception if the port had not yet run or was already completed.
Signals to the downstream input port that an error has occurred, and that no more rows
will be sent.
Also logs the error.
Declaration
public void SendError(string subcategory)Parameters
| Type | Name | Description |
|---|---|---|
| String | subcategory | The logging sub category, which will be dot separated and appended to the OutputPortBaseStateFailed category string. It should categorize the reason for the error. |
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Port state unexpected. |
SendError(String, Exception)
Activates (if needed) and completes the port with an Error state, or throws
an exception if the port had not yet run or was already completed.
Signals to the downstream input port that an error has occurred, and that no more rows
will be sent.
Also logs the error.
Declaration
public void SendError(string subcategory, Exception exception)Parameters
| Type | Name | Description |
|---|---|---|
| String | subcategory | The logging sub category, which will be dot separated and appended to the OutputPortBaseStateFailed category string. It should categorize the reason for the error. |
| Exception | exception | The exception that caused the error, or |
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Port state unexpected. |
SendError(String, Exception, String, String[])
Activates (if needed) and completes the port with an Error state, or throws
an exception if the port had not yet run or was already completed.
Signals to the downstream input port that an error has occurred, and that no more rows
will be sent.
Also logs the error.
Declaration
public void SendError(string subcategory, Exception exception, string message, params string[] args)Parameters
| Type | Name | Description |
|---|---|---|
| String | subcategory | The logging sub category, which will be dot separated and appended to the OutputPortBaseStateFailed category string. It should categorize the reason for the error. |
| Exception | exception | The exception that caused the error, or |
| String | message | The message, or |
| String[] | args | Any arguments used by the message. |
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Port state unexpected. |
SendError(String, String, String[])
Activates (if needed) and completes the port with an Error state, or throws
an exception if the port had not yet run or was already completed.
Signals to the downstream input port that an error has occurred, and that no more rows
will be sent.
Also logs the error.
Declaration
public void SendError(string subcategory, string message, params string[] args)Parameters
| Type | Name | Description |
|---|---|---|
| String | subcategory | The logging sub category, which will be dot separated and appended to the OutputPortBaseStateFailed category string. It should categorize the reason for the error. |
| String | message | The message, or |
| String[] | args | Any arguments used by the message. |
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Port state unexpected. |
SendSucceeded()
Activates (if needed) and completes the port with a Succeeded state, or throws
an exception if the port had not yet run or was already completed.
Signals to the downstream input port that all rows (if any) have been successfully sent,
and that no more rows will be sent.
Declaration
public void SendSucceeded()Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Port state unexpected. |
ToLongString()
Returns a verbose description of this instance.
Declaration
public string ToLongString()Returns
| Type | Description |
|---|---|
| String |
ToString()
Returns a description of this instance.
Note: This method is thread-safe.
Declaration
public override string ToString()Returns
| Type | Description |
|---|---|
| String |