Branch data     Line data    Source code

       1                 :             : // Copyright 2026 HPActor Contributors
       2                 :             : //
       3                 :             : // Licensed under the Apache License, Version 2.0 (the "License");
       4                 :             : // you may not use this file except in compliance with the License.
       5                 :             : // You may obtain a copy of the License at
       6                 :             : //
       7                 :             : //     http://www.apache.org/licenses/LICENSE-2.0
       8                 :             : //
       9                 :             : // Unless required by applicable law or agreed to in writing, software
      10                 :             : // distributed under the License is distributed on an "AS IS" BASIS,
      11                 :             : // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      12                 :             : // See the License for the specific language governing permissions and
      13                 :             : // limitations under the License.
      14                 :             : 
      15                 :             : #pragma once
      16                 :             : 
      17                 :             : #include <hpactor/actor/abstract_actor.hpp>
      18                 :             : #include <hpactor/mailbox/mailbox_policy.hpp>
      19                 :             : #include <hpactor/ref/actor_address.hpp>
      20                 :             : #include <hpactor/types/types.hpp>
      21                 :             : 
      22                 :             : namespace hpactor {
      23                 :             : 
      24                 :             : // Forward declarations
      25                 :             : class ActorSystem;
      26                 :             : namespace net {
      27                 :             : class Transport;
      28                 :             : class IServiceDiscovery;
      29                 :             : class ActorLocationCache;
      30                 :             : } // namespace net
      31                 :             : 
      32                 :             : // -----------------------------------------------------------------------------
      33                 :             : // ActorProxy - reference to a remote actor
      34                 :             : // -----------------------------------------------------------------------------
      35                 :             : // ActorProxy represents an actor on a remote node. It holds the actor's
      36                 :             : // address and a reference to the transport used to communicate with it.
      37                 :             : // Messages sent to a remote actor go through the transport layer.
      38                 :             : // -----------------------------------------------------------------------------
      39                 :             : class ActorProxy {
      40                 :             :   public:
      41                 :             :     // Create an actor proxy for a remote actor
      42                 :             :     // The transport pointer must outlive this proxy
      43                 :             :     ActorProxy(ActorAddress address, net::Transport* transport);
      44                 :             : 
      45                 :             :     // Create an actor proxy from address + system (resolves transport
      46                 :             :     // internally). Used by ActorContext::resolve() for lazy proxy creation.
      47                 :             :     ActorProxy(const ActorAddress& addr, ActorSystem* system);
      48                 :             : 
      49                 :             :     // Get the actor's address
      50                 :           6 :     ActorAddress address() const {
      51                 :           6 :         return address_;
      52                 :             :     }
      53                 :             : 
      54                 :             :     // Get the endpoint where this actor resides
      55                 :           2 :     EndPoint endpoint() const {
      56                 :           2 :         return address_.endpoint;
      57                 :             :     }
      58                 :             : 
      59                 :             :     // Service discovery for address resolution (set by ActorSystem, may be
      60                 :             :     // null).
      61                 :             :     net::IServiceDiscovery* discovery_ = nullptr;
      62                 :             :     // Location cache for ActorId→EndPoint caching (set by ActorSystem, may be
      63                 :             :     // null).
      64                 :             :     net::ActorLocationCache* location_cache_ = nullptr;
      65                 :             : 
      66                 :             :     void set_discovery(net::IServiceDiscovery* d) {
      67                 :             :         discovery_ = d;
      68                 :             :     }
      69                 :             :     void set_location_cache(net::ActorLocationCache* c) {
      70                 :             :         location_cache_ = c;
      71                 :             :     }
      72                 :             : 
      73                 :             :     // Check if this is a local actor (always false for proxy)
      74                 :           2 :     bool is_local() const {
      75                 :           2 :         return false;
      76                 :             :     }
      77                 :             : 
      78                 :             :     // Check if this actor is valid (has a valid address)
      79                 :           3 :     explicit operator bool() const {
      80                 :           3 :         return address_.operator bool();
      81                 :             :     }
      82                 :             : 
      83                 :             :     // Send a message to this actor (fire-and-forget)
      84                 :             :     void send(const ActorAddress& target, TypedMessage msg);
      85                 :             : 
      86                 :             :     // Try-send returning local proxy admission result.
      87                 :             :     // Returns Accepted if the message was handed to the transport layer,
      88                 :             :     // or ActorNotFound if no transport is available. This is a "best effort"
      89                 :             :     // result — the remote node's admission outcome is not known locally.
      90                 :             :     mailbox::EnqueueResult try_send(const ActorAddress& target, TypedMessage msg,
      91                 :             :                                     mailbox::DeliveryOptions options = {});
      92                 :             : 
      93                 :             :     // Access the underlying transport (for internal use)
      94                 :           1 :     net::Transport* transport() const {
      95                 :           1 :         return transport_;
      96                 :             :     }
      97                 :             : 
      98                 :             :   private:
      99                 :             :     ActorAddress address_;
     100                 :             :     net::Transport* transport_;     // Non-owning pointer to the transport
     101                 :             :     ActorSystem* system_ = nullptr; // Non-owning pointer for dead-letter
     102                 :             :                                     // capture
     103                 :             : };
     104                 :             : 
     105                 :             : } // namespace hpactor