grpc.framework.base package¶

Submodules¶

grpc.framework.base.exceptions module¶

Exceptions defined and used by the base layer of RPC Framework.

exception grpc.framework.base.exceptions.NoSuchMethodError[source]¶

Bases: exceptions.Exception

Indicates that an operation with an unrecognized name has been called.

grpc.framework.base.implementations module¶

Entry points into the ticket-exchange-based base layer implementation.

grpc.framework.base.implementations.back_link(servicer, work_pool, transmission_pool, utility_pool, default_timeout, maximum_timeout)[source]¶

Factory function for creating interfaces.BackLinks.

Parameters:

servicer – An interfaces.Servicer for servicing operations. work_pool – A thread pool to be used for doing work within the created BackLink object. transmission_pool – A thread pool to be used within the created BackLink object for transmitting values to a joined ForeLink object. utility_pool – A thread pool to be used within the created BackLink object for utility tasks. default_timeout – A length of time in seconds to be used as the default time alloted for a single operation. maximum_timeout – A length of time in seconds to be used as the maximum time alloted for a single operation.

Returns:

An interfaces.BackLink.

grpc.framework.base.implementations.front_link(work_pool, transmission_pool, utility_pool)[source]¶

Factory function for creating interfaces.FrontLinks.

Parameters:	work_pool – A thread pool to be used for doing work within the created FrontLink object. transmission_pool – A thread pool to be used within the created FrontLink object for transmitting values to a joined RearLink object. utility_pool – A thread pool to be used within the created FrontLink object for utility tasks.
Returns:	An interfaces.FrontLink.

grpc.framework.base.in_memory module¶

In-memory implementations of base layer interfaces.

class grpc.framework.base.in_memory.Link(pool)[source]¶

Bases: grpc.framework.base.interfaces.ForeLink, grpc.framework.base.interfaces.RearLink

A trivial implementation of interfaces.ForeLink and interfaces.RearLink.

accept_back_to_front_ticket(ticket)[source]¶

See interfaces.RearLink.accept_back_to_front_ticket for specification.

accept_front_to_back_ticket(ticket)[source]¶

See interfaces.ForeLink.accept_front_to_back_ticket for specification.

join_fore_link(fore_link)[source]¶

See interfaces.RearLink.join_fore_link for specification.

join_rear_link(rear_link)[source]¶

See interfaces.ForeLink.join_rear_link for specification.

grpc.framework.base.interfaces module¶

Interfaces defined and used by the base layer of RPC Framework.

class grpc.framework.base.interfaces.Back[source]¶

Bases: grpc.framework.base.interfaces.End

Serverish objects that perform the work of operations.

class grpc.framework.base.interfaces.BackLink[source]¶

Bases: grpc.framework.base.interfaces.Back, grpc.framework.base.interfaces.RearLink

Serverish objects that operate by sending and receiving tickets.

class grpc.framework.base.interfaces.BackToFrontTicket[source]¶

Bases: grpc.framework.base.interfaces.BackToFrontTicket

A sum type for all values sent from a back to a front.

operation_id¶

A unique-with-respect-to-equality hashable object identifying a particular operation.

sequence_number¶

A zero-indexed integer sequence number identifying the ticket’s place among all the tickets sent from back to front for this particular operation.

kind¶

A Kind value describing the overall kind of ticket.

payload¶

A customer payload object. Must be present if kind is Kind.CONTINUATION. May be None if kind is Kind.COMPLETION. Must be None otherwise.

class Kind[source]¶

Bases: enum.Enum

Identifies the overall kind of a BackToFrontTicket.

CANCELLATION = <Kind.CANCELLATION: 'cancellation'>¶

COMPLETION = <Kind.COMPLETION: 'completion'>¶

CONTINUATION = <Kind.CONTINUATION: 'continuation'>¶

EXPIRATION = <Kind.EXPIRATION: 'expiration'>¶

RECEPTION_FAILURE = <Kind.RECEPTION_FAILURE: 'reception failure'>¶

SERVICED_FAILURE = <Kind.SERVICED_FAILURE: 'serviced failure'>¶

SERVICER_FAILURE = <Kind.SERVICER_FAILURE: 'servicer failure'>¶

TRANSMISSION_FAILURE = <Kind.TRANSMISSION_FAILURE: 'transmission failure'>¶

class grpc.framework.base.interfaces.End[source]¶

Bases: object

Common type for entry-point objects on both sides of an operation.

add_idle_action(action)[source]¶

Adds an action to be called when this End has no ongoing operations.

Parameters:	action – A callable that accepts no arguments.

operation_stats()[source]¶

Reports the number of terminated operations broken down by outcome.

Returns:	A dictionary from Outcome value to an integer identifying the number of operations that terminated with that outcome.

class grpc.framework.base.interfaces.ForeLink[source]¶

Bases: object

Accepts back-to-front tickets and emits front-to-back tickets.

accept_back_to_front_ticket(ticket)[source]¶

Accept a BackToFrontTicket.

Parameters:	ticket – Any BackToFrontTicket.

join_rear_link(rear_link)[source]¶

Mates this object with a peer with which it will exchange tickets.

class grpc.framework.base.interfaces.Front[source]¶

Bases: grpc.framework.base.interfaces.End

Clientish objects that afford the invocation of operations.

operate(name, payload, complete, timeout, subscription, trace_id)[source]¶

Commences an operation.

Parameters:

name – The name of the method invoked for the operation. payload – An initial payload for the operation. May be None. complete – A boolean indicating whether or not additional payloads to be sent to the servicer may be supplied after this call. timeout – A length of time in seconds to allow for the operation. subscription – A ServicedSubscription for the operation. trace_id – A uuid.UUID identifying a set of related operations to which this operation belongs.

Returns:

An Operation object affording information and action about the operation in progress.

class grpc.framework.base.interfaces.FrontLink[source]¶

Bases: grpc.framework.base.interfaces.Front, grpc.framework.base.interfaces.ForeLink

Clientish objects that operate by sending and receiving tickets.

class grpc.framework.base.interfaces.FrontToBackTicket[source]¶

Bases: grpc.framework.base.interfaces.FrontToBackTicket

A sum type for all values sent from a front to a back.

operation_id¶

A unique-with-respect-to-equality hashable object identifying a particular operation.

sequence_number¶

A zero-indexed integer sequence number identifying the ticket’s place among all the tickets sent from front to back for this particular operation. Must be zero if kind is Kind.COMMENCEMENT or Kind.ENTIRE. Must be positive for any other kind.

kind¶

A Kind value describing the overall kind of ticket.

name¶

The name of an operation. Must be present if kind is Kind.COMMENCEMENT or Kind.ENTIRE. Must be None for any other kind.

subscription¶

An ServicedSubscription.Kind value describing the interest the front has in tickets sent from the back. Must be present if kind is Kind.COMMENCEMENT or Kind.ENTIRE. Must be None for any other kind.

trace_id¶

A uuid.UUID identifying a set of related operations to which this operation belongs. May be None.

payload¶

A customer payload object. Must be present if kind is Kind.CONTINUATION. Must be None if kind is Kind.CANCELLATION. May be None for any other kind.

timeout¶

An optional length of time (measured from the beginning of the operation) to allow for the entire operation. If None, a default value on the back will be used. If present and excessively large, the back may limit the operation to a smaller duration of its choice. May be present for any ticket kind; setting a value on a later ticket allows fronts to request time extensions (or even time reductions!) on in-progress operations.

class Kind[source]¶

Bases: enum.Enum

Identifies the overall kind of a FrontToBackTicket.

CANCELLATION = <Kind.CANCELLATION: 'cancellation'>¶

COMMENCEMENT = <Kind.COMMENCEMENT: 'commencement'>¶

COMPLETION = <Kind.COMPLETION: 'completion'>¶

CONTINUATION = <Kind.CONTINUATION: 'continuation'>¶

ENTIRE = <Kind.ENTIRE: 'entire'>¶

EXPIRATION = <Kind.EXPIRATION: 'expiration'>¶

RECEPTION_FAILURE = <Kind.RECEPTION_FAILURE: 'reception failure'>¶

SERVICED_FAILURE = <Kind.SERVICED_FAILURE: 'serviced failure'>¶

SERVICER_FAILURE = <Kind.SERVICER_FAILURE: 'servicer failure'>¶

TRANSMISSION_FAILURE = <Kind.TRANSMISSION_FAILURE: 'transmission failure'>¶

class grpc.framework.base.interfaces.Operation[source]¶

Bases: object

Representation of an in-progress operation.

consumer¶

A stream.Consumer into which payloads constituting the operation’s input may be passed.

context¶

An OperationContext affording information and action about the operation.

cancel()[source]¶

Cancels this operation.

class grpc.framework.base.interfaces.OperationContext[source]¶

Bases: object

Provides operation-related information and action.

trace_id¶

A uuid.UUID identifying a particular set of related operations.

add_termination_callback(callback)[source]¶

Adds a function to be called upon operation termination.

Parameters:	callback – A callable that will be passed an Outcome value.

fail(exception)[source]¶

Indicates that the operation has failed.

Parameters:	exception – An exception germane to the operation failure. May be None.

is_active()[source]¶

Describes whether the operation is active or has terminated.

time_remaining()[source]¶

Describes the length of allowed time remaining for the operation.

Returns:	A nonnegative float indicating the length of allowed time in seconds remaining for the operation to complete before it is considered to have timed out.

class grpc.framework.base.interfaces.Outcome[source]¶

Bases: enum.Enum

Operation outcomes.

CANCELLED = <Outcome.CANCELLED: 'cancelled'>¶

COMPLETED = <Outcome.COMPLETED: 'completed'>¶

EXPIRED = <Outcome.EXPIRED: 'expired'>¶

RECEPTION_FAILURE = <Outcome.RECEPTION_FAILURE: 'reception failure'>¶

SERVICED_FAILURE = <Outcome.SERVICED_FAILURE: 'serviced failure'>¶

SERVICER_FAILURE = <Outcome.SERVICER_FAILURE: 'servicer failure'>¶

TRANSMISSION_FAILURE = <Outcome.TRANSMISSION_FAILURE: 'transmission failure'>¶

class grpc.framework.base.interfaces.RearLink[source]¶

Bases: object

Accepts front-to-back tickets and emits back-to-front tickets.

accept_front_to_back_ticket(ticket)[source]¶

Accepts a FrontToBackTicket.

Parameters:	ticket – Any FrontToBackTicket.

join_fore_link(fore_link)[source]¶

Mates this object with a peer with which it will exchange tickets.

class grpc.framework.base.interfaces.ServicedIngestor[source]¶

Bases: object

Responsible for accepting the result of an operation.

consumer(operation_context)[source]¶

Affords a consumer to which operation results will be passed.

Parameters:	operation_context – An OperationContext object for the current operation.
Returns:	A stream.Consumer to which the results of the current operation will be passed.
Raises:	abandonment.Abandoned – If the operation has been aborted and there no longer is any reason to service the operation.

class grpc.framework.base.interfaces.ServicedSubscription[source]¶

Bases: object

A sum type representing a serviced’s interest in an operation.

kind¶

A Kind value.

ingestor¶

A ServicedIngestor. Must be present if kind is Kind.FULL. Must be None if kind is Kind.TERMINATION_ONLY or Kind.NONE.

class Kind[source]¶

Bases: enum.Enum

Kinds of subscription.

FULL = <Kind.FULL: 'full'>¶

NONE = <Kind.NONE: 'none'>¶

TERMINATION_ONLY = <Kind.TERMINATION_ONLY: 'termination only'>¶

class grpc.framework.base.interfaces.Servicer[source]¶

Bases: object

Interface for service implementations.

service(name, context, output_consumer)[source]¶

Services an operation.

Parameters:	name – The name of the operation. context – A ServicerContext object affording contextual information and actions. output_consumer – A stream.Consumer that will accept output values of the operation.
Returns:	A stream.Consumer that will accept input values for the operation.
Raises:	exceptions.NoSuchMethodError – If this Servicer affords no method with the given name. abandonment.Abandoned – If the operation has been aborted and there no longer is any reason to service the operation.

grpc.framework.base.null module¶

Null links that ignore tickets passed to them.

grpc.framework.base.util module¶

Utilities helpful for working with the base layer of RPC Framework.

grpc.framework.base.util.full_serviced_subscription(ingestor)[source]¶

Creates a “full” interfaces.ServicedSubscription object.

Parameters:	ingestor – An interfaces.ServicedIngestor.
Returns:	An interfaces.ServicedSubscription object indicating a full subscription.

grpc.framework.base.util.none_serviced_subscription()[source]¶

Creates a “none” interfaces.ServicedSubscription object.

Returns:	An interfaces.ServicedSubscription indicating no subscription to an operation’s results (such as would be the case for a fire-and-forget operation invocation).

grpc.framework.base.util.termination_only_serviced_subscription()[source]¶

Creates a “termination only” interfaces.ServicedSubscription object.

Returns:	An interfaces.ServicedSubscription indicating that the front-side customer is interested only in the overall termination outcome of the operation (such as completion or expiration) and would ignore the actual results of the operation.

grpc.framework.base.util.wait_for_idle(end)[source]¶

Waits for an interfaces.End to complete all operations.

Parameters:	end – Any interfaces.End.

Module contents¶